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PREFACE 



MANUAL OBJECTIVES 

The goal of this manual is to provide information necessary to prepare 
a conventional I/O driver for RSX-llM and subsequently incorporate it 
into an operational user-tailored system. A "conventional" driver is 
best explained by example. Disks and unit record devices are 
considered conventional; the LPS-11, UDC-11, and TMll are considered 
unconventional. Complexity of device servicing requirements sets the 
dividing line, a line not easily established in black-and-white terms. 



INTENDED AUDIENCE 

The manual assumes that you understand the device for which you are 
writing a driver, and that you are familiar with the PDP-11 computer, 
its peripheral devices, and the software supplied with an RSX-llM 
system. Although this manual is organized tutorially, the intended 
audience is assumed to be at a system programmer level of expertise; 
thus, the manual does not contain definitions of data processing terms 
and concepts familiar to senior level professionals. 



ASSOCIATED DOCUMENTS 

Familiarity with the system implies an in-depth exposure to the 
following RSX-llM manuals: 

1. System Generation Manual 



2. 


I/O Drivers Reference Manual 


3. 


Executive Reference Manual 


4. 


Utilities Procedures Manual 


5. 


I/O Operations Reference Manual 



As adjuncts to this manual, you are advised to study existing I/O 
drivers. The RF-11 disk driver is a good example of an NPR device and 
the TA-11 (cassette) is illustrative of a programmed I/O device. In 
addition, a perusal of Executive source code contained in the files 
lOSUB, SYSXT, DRQIO, BFCTL, and DRDSP (stored under UIC [11,10] on the 
Executive source disk) is recommended. 

Other manuals closely allied to the purposes of this document are 
described briefly in the RSX-llM/RSX-llS Documentation Directory. The 
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Documentation Directory defines the intended readership of each manual 
in the RSX-llM/RSX-llS set and provides a brief synopsis of each 
manual's contents. 



STRDCTORE OF THIS DOCUMENT 

This document proceeds from chapter to chapter toward increasing 
levels of implementation detail. 

Chapter 1 is a general introduction to I/O drivers in the PSX-llM 
system. 

Chapter 2 is a functional description of the RSX-llM device-level I/O 
system. It discusses both data structure and code requirements. 

Chapter 3 details how to incorporate a user-written driver into the 
system. 

Together, Chapters 1, 2, and 3 provide a complete understanding of the 
requirements that must be met in creating a system that contains a 
user-written driver. 

Chapter 4 provides programming-level details on I/O data structures 
and on drivers that service several controllers. 

Chapter 5 discusses all the I/O-related Executive services. 

Chapter 6 gives two examples of user-written drivers. 

Appendix A describes the Address Doubleword. 

Appendix B outlines special considerations for PDP-11/70 NPR device 
drivers. 

Appendix C lists system macros that supply symbolic offsets for system 
data structures. 
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CHAPTER 1 
INTRODUCTION TO I/O DRIVERS 



The software supplied by DIGITAL for an RSX-llM system includes I/O 
drivers for a number of standard I/O devices. An I/O driver is a part 
of the RSX-llM Executive that services one type of I/O device. A 
driver may handle one or several controllers, each with one or several 
device-units attached. 



1.1 RESIDENT AND LOADABLE DRIVERS 

A driver can be resident or loadable. A resident driver is a 
permanent part of the Executive, built in at SYSGEN. A loadable 
driver, while also part of the Executive, can be added to or unloaded 
from a system almost at will by means of MCR or VMR commands. During 
the SYSGEN dialog, you can specify that you want this facility. 

Making drivers loadable can result in a smaller Executive, and thus 
more space for user tasks. Any driver that is not needed for a period 
of time can be unloaded from the system. For example, suppose your 
system has both a paper-tape reader and a card reader. Suppose that 
only one of them is connected to the system at any one time. You 
could load the driver for the online device and unload the other 
driver, thus reducing the size of the Executive. 

A loadable user-written driver is easier to incorporate into a system 
and easier to debug than a resident one. A resident driver can only 
be incorporated into a system at SYSGEN; the Executive must be 
rebuilt and the system bootstrapped each time it is reincorporated 
during debugging. A loadable driver can be incorporated into a system 
with a single MCR command. Incorporating and debugging user-written 
drivers are discussed in Chapter 3. 



1.2 FUNCTION OF AN I/O DRIVER 

An I/O driver is an asynchronous process (not a task) that calls and 
is called by the Executive to service an external I/O device or 
devices. The role of an I/O driver in the RSX-llM I/O structure is 
specific and limited. A driver performs the following functions: 



• 



Receives and services interrupts from its I/O device (s) 



• Initiates I/O operations when requested to do so by the 
Executive. 

• Cancels in-progress I/O operations. 

• Performs other (device-specific) functions upon power failure 
and device timeout. 



1-1 



INTRODUCTION TO I/O DRIVERS 

As an integral part of the Executive, a driver possesses its own 
context, allows or disallows interrupts, and synchronizes its access 
to shared data bases with that of other Executive processes. (It may 
also synchronize with itself; a driver can handle several device 
controllers, each with several device-units, all operating in 
parallel.) A user-written driver must adhere to RSX-llM programming 
conventions in order to ensure the integrity of the Executive. 
Section 2.5 and Chapter 4 discuss these conventions. 
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CHAPTER 2 
THE RSX-llM I/O SYSTEM—PHILOSOPHY AND STRUCTURE 



2.1 I/O PHILOSOPHY 

Memory constraints and RSX-llD compatibility requirements dominated 
the design philosophy and strategy used in creating RSX-llM. To meet 
its performance and space goals, the RSX-llM I/O system attempts to 
centralize common functions, thus eliminating the inclusion of 
repetitive code in each and every driver in the system. To achieve 
this centralization, a substantial effort has been expended in 
designing RSX-llM's data structures. These structures are used to 
drive the centralized routines; the effect is to reduce substantially 
the size of individual I/O drivers. The table structures require 
space and must be considered with the total size of the I/O system. 
Nevertheless, the size reduction effected by the centralization of 
functions, combined with table-driven design, enables RSX-llM to meet 
its intended memory and performance goals. 



2 . 2 STRUCTURE 
This section: 

1. Places an I/O driver in the context of the overall RSX-llM 
I/O system; 

2. Establishes the responsibilities of an I/O driver, and 

3. Functionally describes the driver's interface to the 
Executive subroutines and the I/O data structures. 



2.2.1 I/O Hierarchy 

The RSX-llM I/O system is structured as a loose hierarchy. The term 
"loose" indicates that the hierarchy can be entered at any of its 
levels; this characteristic is contrasted to "tight" hierarchies that 
permit entry only from the top level. Tight hierarchies exist 
principally for security and protection, but are costly in their 
consumption of equipment resources. Figure 2-1 shows the loose I/O 
system hierarchy. 



2.2.1.1 FCS/RMS - At the top of the hierarchy are File Control 
Services (FCS) and Record Management Services (RMS) , which provide 
device-independent access to devices included in a given system 
configuration. The user task has tvro levels with which to interface 
with FCS or RMS; Get/Put and Read/Write. Get/Put facilitates the 
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movement of data records, whereas Read/Write provides a more basic 
level of access affording more direct control over data movement 
between a task and peripheral devices. 



Privileged 



Non-privileged 



FCP 



FCS/RMS 



QIO 

directive 



User I/O 
request 



Device- 
independent 



QIO 
directive 



Device- 
dependent 



QIO 

directive 
service 



User state 
System state 
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Executive 
I/O subroutines 



Device interrupt - 



I/O 
driver 



Figure 2-1 I/O Control Flow 



The discussion of FCS and RMS is brief because their existence is 
completely transparent to the driver and rarely concerns the writer of 
a conventional driver. FCS or RMS accepts a user request, interprets 
it, and translates it into a series of low-level system directives 
known as QIOs. 



2.2.1.2 QIO - The QIO directive is the lowest level of task I/O. Any 
task may issue a QIO directive. The QIO directive allows direct 
control over devices that are connected to a system and that have an 
I/O driver. The QIO directive forces all I/O requests from user tasks 
to go through the Executive. The Executive works to prevent tasks 
from destructively interfering with each other and with the Executive 
itself. 
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2.2.1.3 Executive I/O Processing - The processing of I/O requests by 
the Executive I/O system is accomplished by means of; 

1. File Control Primitives (FCP) , and 

2. A collection of Executive components consisting of: 

a. QIO directive processing; 

b. I/0-related subroutines, and 

c. The I/O drivers. 

FCP is responsible for maintaining the structure and integrity of data 
stored on file-structured volumes. It maps virtual block numbers to 
logical block numbers, extends files, and makes volume-protection 
checks. The driver converts a logical block number into a physical 
address on a file-structured device. No direct connection exists 
between FCP and a driver. 

FCP is a privileged task, and requires a partition in which to 
execute. Drivers, on the other hand, are specialized system 
processes, not tasks. 

The I/O services provided by the Executive consist of QIO directive 
processing, and a collection of subroutines used by drivers to obtain 
I/O requests, facilitate interrupt handling, and return status upon 
completion of an I/O request (actual control of the device is 
performed by the driver) . These subroutines are examined in detail in 
Chapter 5. Executive subroutine services and QIO directive processing 
are shown as distinct components but are, in fact, both part of the 
Executive. These subroutines centralize common driver functions, thus 
eliminating duplicate code sequences among drivers. 



2.2.2 Role of I/O Driver in RSX-llM 

Every I/O driver in the RSX-llM system has five entry points: 

1. Device interrupt* 

2. I/O initiator 

3. Device timeout 

4. Cancel I/O 

5. Power failure 

The first entry point is entered by a hardware interrupt; the other 
four are entered by calls from the Executive. Functional details 
regarding these entry points follow. 



2.2.2.1 Device Interrupt - Control passes to this entry point when a 
device previously initiated by the driver completes an I/O operation 
and causes an interrupt in the central processor. The connection 
between the device and the driver in this instance is direct; the 
Executive is not involved. 



* A device may trigger more than one distinct interrupt entry. For 
example, a full-duplex device would have two. 
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2.2.2,2 I/O Initiator - The Executive calls this entry point to 
inform the driver that work for it is waiting to be done. In effect, 
this is a wakeup signal for the driver. 



2.2.2.3 Device Timeout - When a driver initiates an I/O operation, it 
can establish a timeout count. If the function then fails to complete 
within the specified time interval, the Executive notes the time lapse 
and calls the driver at this entry point. 



2.2.2.4 Cancel I/O - A number of circumstances arise within the 
system that require a driver to terminate an in-progress I/O 
operation. When such a termination becomes necessary, a task so 
informs the Executive, which then relays the request to the driver by 
calling it at the cancel I/O entry point. 



2.2.2.5 Power Failure - The Executive calls the driver's power- 
failure entry point in three different circumstances: 

1. When power is restored after a failure 

2. When the system is bootstrapped 

3. When the driver is loaded (if it is a loadable, as opposed to 
a resident, driver) 

Power Restore - Two conditions can initiate a call to the driver when 
power is restored following a power failure. First, the Executive 
automatically calls the power-failure entry point when power is 
restored any time the controller is busy (that is, when I/O is in 
progress). Second, a driver has the option to be called regardless of 
the existence of an outstanding I/O operation at the time the power is 
restored (refer to the description of the UC.PWF bit symbol in Section 
4.1.4.1). Frequently, a driver's response to a power failure or to an 
I/O failure is identical to that when its device times out; in such a 
case, the power-failure entry point may simply be a return, because 
recovery will eventually be effected by means of the timeout entry 
point. 

Bootstrap - When the system is bootstrapped, a power-failure interrupt 
is simulated. This simulation gives drivers the opportunity to carry 
out any appropriate pre-operational initialization. 

Load - The MCR command LOA[D] calls a loadable driver at its 
power-failure entry point if the device is online and UC.PWF (refer to 
Section 4.1.4.1) is set. 



2.2.2.6 Summary — Role of an I/O Driver - Functionally, the driver in 
RSX-llM is responsible for: 

1. Servicing device interrupts 

2. Initiating I/O operations 

3. Cancelling in-progress I/O opierations 

4. Performing device-related functions upon the occurrence of 
timeout or power failure 
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A driver exists as an integral part of the Executive; it can call, 
and be called by, the Executive. The driver initiates device I/O 
operations directly and receives device interrupts directly. All 
other entry points are entered by means of Executive calls. A driver 
never receives a QIO request directly, and has no direct interaction 
with FCP. 



2.3 DATA STRUCTURES 

An I/O driver interacts with seven data structures: 

1. Device Control Blocks (DCBs) 

2. Unit Control Blocks (UCBs) 

3. Status Control Blocks (SCBs) 

4. The I/O Packet 

5. The I/O Queue 

6. The Fork List 

7. Device Interrupt Vector 

The first four of these data structures are especially important to 
the driver, because it is by means of these data structures that all 
I/O operations are effected. They also serve as communication and 
coordination vehicles between the Executive and individual drivers. 

The I/O Queue and the Fork List are actually Executive data 
structures, but to convey the complete interaction of an I/O driver 
with the Executive, we will also describe their role in the system. 
The I/O Queue is a list of I/O packets built by the QIO directive, 
principally from information in the caller's Directive Parameter Block 
(DPB) . The Fork List synchronizes access to shared Executive data 
structures. 

Entry to a driver following a device interrupt is accomplished through 
the appropriate hardware device interrupt vector. As will be seen, 
writers of resident drivers are responsible for properly initializing 
this vector. It is discussed in conjunction with the data structures 
associated with a driver. 



2.3.1 The Device Control Block (DCB) 

At least one DCB exists for each type of device appearing in a system 
(device type should not be equated with device-unit) . The function of 
the DCB is to describe the static characteristics (rather than 
execution-time information) of both the device controller and the 
units attached to the controller. All the DCBs in a system form a 
forward-linked list, with the last DCB having a link of zero. Most of 
the data in the DCB is established in the assembly source for the 
driver data structure. The DCB is used by the QIO directive 
processing code in the Executive and not by the driver. 



2-5 



THE RSX-llM I/O SYSTEM — PHILOSOPHY AND STRUCTURE 

2.3.2 The Unit Control Block (UCB) 

One UCB exists for each device-unit attached to a system. Much of the 
information in the UCB is static, though a few dynamic parameters 
exist.* For example, the redirect pointer, which reflects the results 
of an MCR Redirect command, is updated dynamically. As with the DCS, 
most of the UCB is established in the assembly source; however, its 
contents are used and modified by both the Executive and the driver, 
though modification of a given datum is usually done by either the 
Executive or the driver, but not both. 



2.3.3 The Status Control Block (SCB) 

One SCB exists for each device controller in the system. This is true 
even if the controller handles more than one device-unit (like the 
RKll Controller). Line multiplexers such as the DHll and DJll are 
considered to have one controller for each line because all lines may 
transfer in parallel. Most of the information in the SCB is dynamic. 
Both the Executive and the driver use the SCB. 



2.3.3.1 Interrelation of the I/O Control Blocks - This section 
represents the interrelationship among the DCB, UCB, and SCB without 
entering into the detailed contents of the control blocks, leaving 
such a discussion to be pursued in Chapter 4. 

Figure 2-2 shows the data structure that would result for three LA36 
DECwr iters interfaced by means of a DHll multiplexer. The structure 
requires one DCB, three UCBs, and three SCBs, because the activity on 
all three units can proceed in parallel. 

Figure 2-3 depicts the internal data structure for an RKll disk 
controller with three units attached. Note that only one SCB exists 
because only one of the three units can be active at any given time. 

Figure 2-4 shows the data structure for two RKll disk controllers, 
each of which has two drives attached. Here, there are two SCBs, 
because both of the disk controllers can operate in parallel. 

Taken together. Figures 2-2, 2-3, and 2-4 illustrate the strategy 
underlying the existence of three basic I/O control blocks. There 
need be only one DCB for each device type. There may be one or more 
SCBs, depending on the degree of parallelism that is desired or 
possible: one for each device-unit, or one for each controller 
servicing several device-units. The number of UCBs and SCBs, and 
their interrelationships, are uniquely determined by the hardware 
these data structures describe. 

This data structure provides considerable flexibility in configuring 
I/O devices, and, because of the information density in the structures 
themselves, substantially reduces the code requirements of the 
associated drivers. 



^^^w\ 



* From the UCB, however, it is possible to access most of the 

other structures in the I/O data base (see Figure 2-5) . In this "^'^ 

sense the UCB gives access to a large amount of dynamic data. ' 
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Figure 2-2 DHll Terminal I/O Data Structure 





Figure 2-3 RKll Disk I/O Data Structure 
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Figure 2-4 I/O Data Structure for Two RKll Disk Controllers 



2.3.4 The I/O Packet 

An I/O Packet contains information extracted from the QIO DPB, as well 
as other information needed to initiate and terminate I/O requests. 



^SB^Pft.. 



2.3.5 The I/O Queue 

Each time a task makes an I/O request, the Executive performs a series 
of validity checks on the DPB parameters. If these checks prove 
successful, the Executive generates a data structure called an I/O 
Packet. The Executive then inserts the packet into a device-specific, 
priority-ordered list of packets called the I/O Queue. Each I/O 
Queue's listhead is located in the SCB to which the I/O requests 
apply. 

When a device driver needs work, it requests the Executive to dequeue 
the next I/O Packet and deliver it to the requesting driver. 
Normally, the driver does not directly manipulate the I/O Queue.* 



* An exception is the case in which a driver needs to examine an I/O 
packet before it is queued, or in place of having it queued. For the 
driver to accomplish this examination, you must set the bit UC.QUE in 
the control byte (U.CTL) of the UCB (described in Section 4.1.4). 

The most common reason for a driver to examine a packet before queuing 
is that the driver employs a special user buffer, other than the 
normal buffer used in a transfer request. Within the context of the 
requesting task, the driver must address-check and relocate such a 
special buffer. See Section 6.3 for an example of a driver that does 
this. 



0^^S^ 
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2.3.6 The E'ork List 

The Fork List is a mechanism by which RSX-llM splits off processes 
that require access to shared data bases, or that require more CPU 
time to process an interrupt than is compatible with fast, real-time 
response of the overall system. 

A process that calls $FORK requests the Executive to transform it into 
a "fork process" and place it on the Fork List. What this means is 
that a call to $FORK saves a "snapshot" of the process (registers R4 , 
R5, and the PC) in a Fork block. This Fork block is queued on the 
Fork List in FIFO order. 

When a fork process has worked its way to the front of the Fork List, 
R4 and R5 are restored and execution restarts at the statement after 
CALL $FORK. The process is unaware that a pause of indeterminate 
length has elapsed. 

A fork process exists in a status intermediate between an interrupting 
routine and an ordinary task requesting system resources. Routines in 
the system stack — requests for interrupt processing — are run first. 
They can be interrupted only by higher-priority requests. Routines in 
the Fork List are run when the system stack is empty — that is, they 
are completely inter ruptable. Finally, other tasks are run only when 
both the system stack and the Fork List are empty. 

Driver interrupts are processed at priority 7 and are thus 
noninterruptable. By . system convention, no process should run in a 
noninterruptable mode for more than 100 microseconds. This convention 
ensures prompt attention to interrupting real-time events. 

In practice, drivers servicing interrupts drop from priority 7 to a 
lower priority (namely, that of the interrupting source) after issuing 
a few instructions.. Another system convention states that processing 
at this partially interruptable level should not exceed 500 
microseconds. Often, more time than this is required to process an 
interrupt. The Fork List mechanism provides a secondary interrupt 
stack whose members are processed first-in-first-out (FIFO) whenever 
the system stack is empty. 

A process can also call $FORK to access a shared data base — a system 
table, for example. Such access must be strictly controlled to avoid 
conflicts. Under RSX-llM, many drivers can run in parallel; a 
multicontroller driver can run in parallel with itself. In these 
circumstances access to common data bases must be controlled. 

Of the two available methods of controlling such access — interrupt 
lockout and priority queuing — RSX-llM uses priority queuing. The Fork 
List is the queue of requests for such access. Fork processes are 
granted FIFO access to common data bases. Once granted such access, a 
process is guaranteed control of the data base until it exits. 



2.3.7 The Device Interrupt Vector 

The device interrupt vector consists of two consecutive words giving 
the address of the interrupt-service routine and the priority at which 
it is to run (always set to PR7) . The low 4 bits of the second word 
of the interrupt vector must contain the number of the controller that 
interrupts through the vector. This requirement enables a driver to 
service several controllers with few code changes (see Sections 4.2 
and 4.3 for an example and discussion of multicontroller driver 
coding) . Generally, these bits are 0. 
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2.4 EXECUTIVE SERVICES 

The Executive provides services related to I/O drivers that can be 
categorized as pre- and post-driver initiation. The pre-initiation 
services are those performed by the Executive during its processing of 
a QIO directive; these services are not available as Executive calls. 

The goal of pre-driver-initiation processing is to extract from the 
QIC directive all I/O support functions not directly related to the 
actual issuance of a function request to a device. If the outcome of 
pre-driver-initiation processing does not result in the queuing of an 
I/O Packet to a driver, the driver is unaware that a QIO directive was 
issued. Many QIO directives do not result in the initiation of an I/O 
operation. 

The post-initiation services are those available to the driver after 
it has been given control, either by the Executive or as the result of 
an interrupt. They are available as needed by means of Executive 
calls. 

An important concept used in this section and in Section 2.5 is the 
"state" of a process. In RSX-llM, a process can run in one of two 
states, user or system. Drivers operate almost entirely in the system 
state; the programming standards described in Section 2.5 apply to 
system-state processes. 



2.4.1 Pre-Driver Initiation Processing 

In processing a QIO directive, the Executive module DRQIO performs the 
following pre-driver initiation services: 

1. Checks to verify whether the supplied logical unit number 
(LUN) is legal. If not, the directive is rejected. 

2. If the LUN is valid, checks to verify whether a valid UCB 
pointer exists in the Logical Unit Table (LUT) for the 
specified LUN. This test determines if the LUN is assigned. 
If the test fails, the directive is rejected. 

3. If steps 1 and 2 are successful, traces down the redirect 
chain to locate the correct UCB to which the I/O operation 
will actually be directed. 

4. Checks the event flag number (EFN) and the address of the I/O 
Status Block (lOSB) . If either is illegal, the directive is 
rejected. Immediately following validation, the Executive 
resets the subject event flag and clears the lOSB. 

5. Obtains 18 words of dynamic storage and builds the 
device-independent portion of an I/O Packet. 

If steps 1 thru 5 succeed, the Executive sets the directive 
status to +1. 

Note that directive rejections in any of the above steps are 
completely transparent to the driver. Such rejections cause 
a return of carry bit set. 



affiffli|K% 
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6. Checks the validity of the function being requested and, if 
appropriate, checks the buffer address, byte count, and 
alignment requirements for the specified device. 

If any of these checks fails, the Executive calls the I/O 
Finish routine ($IOPIN) . $IOFIN sets the I/O status and 
clears the QIO request from the system. 

7. If the requested function does not require a call to the 
driver, the Executive takes the appropriate actions and calls 
$IOFIN. 

8. If all I/O Packet checks are positive, the Executive places 
the I/O Packet in the driver queue according to the priority 
of the requesting task, or gives the packet to the driver (if 
bit UC.QUE is set — described in Section 4.1.4.1). 



2.4.2 Post-Driver Initiation Services 

Once a driver is given control following an I/O interrupt or by the 
Executive itself, a number of Executive services are available to the 
driver. These services are discussed in detail in Chapter 5. 

However, four Executive services merit special emphasis because 
virtually every driver in the system uses them: 

1. Interrupt Save ($INTSV) 

2. Get Packet ($GTPKT) 

3. Create Fork Process ($FORK) 

4. I/O Done (?IODON or $IOALT) 



2.4.2.1 Interrupt Save ($INTSV)* - Interrupts from a device are 
fielded by the driver. Immediately following the interrupt, the 
driver operates at hardware priority level 7 and is, therefore, 
noninterruptable. If the driver needs a lengthy processing cycle 
(greater than 100 microseconds) to process the interrupt, or if it 
requires the use of any general-purpose registers, it calls $INTSV. 
This call queues external interrupts, alters the hardware priority, 
and provides the calling routine with two free registers to use in 
processing the interrupt. $INTSV is discussed in more detail in 
Section 2.5. 



2.4.2.2 Get Packet ($GTPKT) - The Executive, after it has queued an 
I/O Packet, calls the appropriate driver at its I/0-initiator entry 
point. The driver then immediately calls the Executive routine $GTPKT 
to obtain work.** If work is available, $GTPKT delivers to the driver 
the highest-priority, executable I/O Packet in the driver's I/O queue, 
and sets the SCB status to "busy." If the driver's I/O Queue is empty, 
$GTPKT returns a no-work indication. 



* A loadable driver on a mapped system may not call $INTSV directly. 
See Section 4.3. 

** An exception is a driver that handles special user buffers. Such a 
driver must call certain other Executive routines before calling 
$GTPKT. See Section 6.3 for an example. 
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If the SCB related to the device is already busy, $GTPKT so informs 

the driver, and the driver immediately returns control to the -^^^ 

Executive. 

Note that, from the driver's point of view, no distinction exists 
between no-work and SCB busy, because an I/O operation cannot be 
initiated in either case. 



2.4.2.3 Create Pork Process ($FORK) - Synchronization of access to 
shared data bases is accomplished by creating a fork process. When a 
driver needs to access a shared data base, it must do so as a fork 
process; the driver becomes a fork process by calling $FORK. The SCB 
contains preallocated storage for a 4- or 5-word "fork block". See 
Section 4.1.3.1 for a description of the fork block. Section 5.3 
contains details on $FORK. 

An interrupt routine may not call $FORK directly; the routine must 
first switch to system state by using the INTSV$ macro or calling 
$INTSV (as described in Section 2.4.2.1). Further, the interrupting 
routine's priority is lowered to that of the requesting source. 

After calling $FORK, a routine is fully interruptable (priority 0) , 
and its access to shared system data bases is strictly linear. 



2.4.2.4 I/O Done ($IODON or $IOALT) - at the completion of an I/O 
request, the subroutines $IODON or $IOALT perform a number of 
centralized checks and additional functions: 

Store status if an lOSB address was specified 

Set an event flag, if one was requested 

Determine if a checkpoint request can now be honored 

Determine if an AST should be queued 

$IODON and $IOALT also declare a significant event, resets the SCB and 
device unit status to "idle," and releases the dynamic storage used by 
the completed I/O operation. 



2.5 PROGRAMMING STANDARDS 

RSX-llM I/O drivers function as integral components of the RSX-llM 
Executive. They must follow the same conventions and protocol as the 
Executive itself if they are to avoid complete disruption of system 
service. This manual has been written to enable you to incorporate 
I/O drivers into your system. Failure to observe the internal 
conventions and protocol can result in poor service and reductions in 
system efficiency. 



i^^^lk 
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2.5.1 Process-Like Characteristics of a Driver 

A driver is an asynchronous Executive process. As a process, it 
possesses its own context, allows or disallows interrupts, and 
synchronizes functions within itself (all drivers can be parallel, 
multiunit, multicontroller) and with other Executive processes 
executing in parallel. 

Most RSX-llM drivers are small; their small size is made possible by 
a comprehensive complement of centralized services available by calls 
to the Executive, and by the availability of an information-dense, 
highly formalized I/O data structure. 



2.5.2 Programming Conventions 

Appendix E of the IAS/RSX-11 MACRO-11 Reference Manual describes 
program coding standards. DIGITAL recommends that users refer to 
these standards to assist in preparing standards for their own 
installations. 



2.5.3 Programming Protocol 

Because an I/O driver accepts interrupts directly from the devices it 
controls, the central Executive relies on the driver to follow strict 
programming protocol so that system performance is not degraded. 
Furthermore, the protocol ensures that the driver properly distributes 
shared resources according to user-specified priorities. The protocol 
is summarized in Section 2.5.3.4. 

When a device interrupts, an I/O driver is entered. The driver 
usually calls $INTSV or issues the INTSV$ macro* for common save and 
state-switching services. At the completion of the services provided 
by INTSV$ or $INTSV, the interrupt routine is again given control to 
complete the interrupt service. The exit routine $INTXT restores the 
state prior to switching to the system state, controls the un-nesting 
of interrupts, and makes checks on the state of the system (for 
example, it checks to determine whether it is necessary to switch 
stacks). The Fork Processor linearizes access to shared system data 
bases. The details of all these routines are given in Chapter 5. 

The interrupt vectors for each controller type in low memory contain a 
Program Counter (PC) unique to each interrupting source and a 
Processor Status Word (PS) set with a priority of 7. It is a system 
software convention to use the low-order 4 bits of the PS word to 
encode the controller number for multicontroller drivers. When a 
device interrupt occurs, the hardware pushes the current PS and PC 
onto the current stack and loads the new PC and PS (set at PP7 with 
the controller number in the condition-code bits) from the appropriate 
interrupt vector. The driver then starts executing with interrupts 
locked out. A driver itself may be executing at one of three levels 
of interrupt sensitivity: 



* The system macro INTSV$ simplifies the coding of standard 
interrupt-entry processing (see Section 4.3). 
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1. At priority 7 with interrupts locked out; 

2. At the priority of the interrupting source; thus, interrupt 
levels greater than the priority of the interrupting source 
are permitted, or 

3. At fork level, which is at priority 0. 




2.5.3.2 Processing at the Priority of the Interrupting Source - If 

the driver requires additional processing time or requires the use of 
general-purpose registers, it calls the Interrupt Save routine. 
Loadable drivers on mapped systems must use the INTSV$ macro. All 
other drivers can use the INTSV$ macro or call the SINTSV routine 
directly. The priority at which the caller is to run is included in 
the call to the Interrupt Save routine. The driver sets this priority 
level to that of the interrupting source. 

The Interrupt Save routine sets up the interrupt routine so that it 

can be interrupted by devices with priorities higher than that of the 

interrupting source, and switches to system state if the processor is 
not already in system state. 

The Interrupt Save routine also saves registers R4 and R5 to free 
these registers for the driver. (A standard practice is for the 
driver to set R4 to the address of the interrupting device's SCB, and 
R5 to its UCB address.) An internal programming convention assumes 
that the driver will not require more than these two registers during 
interrupt processing. If it does, the driver must save and restore 
any additional registers it uses. Processing time following the 
return from the Interrupt Save routine should not exceed 500 
microseconds* . 



NOTE 

In actual practice, every driver in the 
system calls the Interrupt Save routine 
on every interrupt. This practice is 
due to. two factors: 

1. It is difficult to service an 
interrupt without using one or two 
registers. 



J«B^ 



* The 500-microsecond period is a guideline. The longer the period 

of time a real-time executive spends at an elevated priority level, 

the less responsive is the system to devices of equal or lower 

priority. This guideline is especially important if the device being 

serviced is at the same or higher priority than a character-interrupt 

device such as the DUll, which is vulnerable to data loss due to _ 

interrupt lockout. ^^h. 
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Most interrupt code can safely be 
executed at the priority of the 
interrupting source. Execution at 
that priority is more desirable in 
terms of system response than 
continuing to execute at the highest 
priority. 



2.5.3.3 Processing at Fork Level - A driver calls $FORK to become 
fully interruptable (so that it conforms to the 500-microsecond time 
limit) , or to access the shared system data base. The INTSV$ macro 
must be issued or the $INTSV routine must be called prior to calling 
$FORK. 

By calling $FORK, the routine becomes fully interruptable and its 

access to system data bases is strictly linear. At fork level, all 

registers are available to the process, and R4 and R5 retain the 
contents they had on entrance to $FORK. 



2.5.3.4 Programming Protocol Summary - Drivers are required to adhere 
to the following internal conventions when processing device 
interrupts: 

1. No registers are available for use unless $INTSV has been 
called or the driver explicitly performs save and restore 
operations. If $INTSV is called, registers R4 and R5 are 
available; any other registers must be saved and restored. 

2. Noninterruptable processing must not exceed twenty 
instructions, and processing at the priority of the 
interrupting source must not exceed 500us. 

3. All modifications to system data bases must be done by a fork 
process. 



2.6 FLOW OP AN I/O REQUEST 

Following an I/O request through the system at the functional level 
(the level at which this chapter is directed) requires that limiting 
assumptions be made about the state of the system when a task issues a 
QIO directive. The following assumptions apply: 

• The system is up and ready to accept an I/O request. All 
required data structures for supporting devices attached to 
the system are intact. 

• The only I/O request in the system is the sample request 
under discussion. 

• The example progresses without encountering any errors that 
would prematurely terminate its data transfer; thus, no 
error paths are discussed. 
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The I/O flow proceeds as described below: 

1. [Task issues QIO directive] 

All Executive directives are called by means of EMT 377. The 
EMT causes the processor to push the PS and PC on the stack 
and to pass control to the Executive's directive processor. 

la. [First-level validity checks] 

The QIO directive processor validates the LUN and UCB 
pointer . 

lb. [Redirect algorithm] 

Because the UCB may have been dynamically redirected by an 
MCR Redirect command, QIO directive processing traces the 
redirect linkage until the target UCB is found. 

Ic. [Additional validity checks] 

The EFN is validated, as well as the address of the I/O 
Status Block (lOSB) . The event flag is reset and the I/O 
status block is cleared. 

2. [Obtain storage for and create an I/O Packet] 

The QIO directive processor now acquires an 18-word block of 
dynamic storage for use as an I/O Packet. It inserts into 
the packet data items that are used subsequently by both the 
Executive and the driver in fulfilling the I/O request. Most 
items originate in the requesting task's Directive Parameter 
Block (DPB) . 

3. [Validate the function requested] 

The function is one of four possible types: 

Control 

No-op 

ACP 

Transfer 

Control functions, with the exception of Attach/Detach, are 
queued to the driver. If the bit UC.ATT is set, 
Attach/Detach will also be queued to the driver. 

No-op functions do not result in data transfers. The 
Executive "performs" them without calling the driver. No-ops 
return a status of IS.SUC in the I/O status block. 

ACP functions may require processing by the file system. 
More typically, the request is a read or write virtual 
function that is transformed into a read or write logical 
function without requiring file-system intervention. When 
transformed into a read or write logical, the function 
becomes a transfer function (by definition) . 

Transfer functions are address checked and queued to the 
proper driver. Then the driver is called at its initiator 
entry point. 
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4. [Driver processing] 
4a. [Request work] 

To obtain work, the driver calls Get Packet ($GTPKT) . $GTPKT 
either provides work, if it exists, or informs the driver 
that no work is available, or that the SCB is busy; if no 
work exists, the driver returns to its caller. If work is 
available, $GTPKT sets the device controller and unit to 
"busy," dequeues an I/O request packet, and returns to the 
driver . 

4b. [Issue I/O] 

From the available data structures, the driver initiates the 
required I/O operation and returns to its caller. A 
subsequent interrupt may inform the driver that the initiated 
function is complete, assuming the device is interrupt- 
driven. 

5. [Interrupt processing] 

When a previously issued I/O operation interrupts, the 
interrupt causes a direct entry into the driver, which 
processes the interrupt according to the programming protocol 
described in Section 2.5, According to the protocol, the 
driver may process the interrupt at priority 7, at the 
priority of the interrupting device, or at fork level. If 
the processing of the I/O request associated with the 
interrupt is still incomplete, the driver initiates further 
I/O on the device (step 4b) . When the processing of an I/O 
request is complete, the driver calls $IODON. 

6. [I/O Done processing] 

$IODON removes the "busy" status from the device unit and 
controller, queues an AST, if required, and determines if a 
checkpoint request pending for the issuing task can now be 
effected. The lOSB and event flag, if specified, are 
updated, and $IODON returns to the driver. The driver 
branches to its initiator entry point and looks for more work 
(step 4a) . This procedure is followed until the driver finds 
the queue empty, whereupon the driver returns to its caller. 

Eventually, the processor is granted to another ready-to-run 
task that issues a QIO directive, starting the I/O flow anew. 



2.7 DATA STRUCTURES AND THEIR INTERRELATIONSHIPS 

This section introduces all the individual control blocks, as well as 
their linkages and use within the system. The following data 
structures comprise the complete set for I/O processing: 

1. Task Header 

2. Window Block (WB) 

3. File Control Block (FCB) 

4. $DEVHD word, the Device Control Block (DCB) , and the Driver 
Dispatch Table (DDT) 
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5. Unit Control Block (UCB) 

6. Status Control Block (SCB) 

7. Volume Control Block (VCB) 

Figure 2-5, which provides the structure for the following discussion, 
shows all the individual data structures and the important link fields 
within them. The numbers on the figure are keyed to the text to 
simplify the discussion and to guide the reader through the data 
structures. 
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process.* (It is one of t 
data structure, the other 
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entry contains a pointer to 
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number (LUN) • 
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wo independent entries in the I/O 
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Figure 2-5 I/O Data Structure 



* In mapped systems, a copy of the Task Header (located in the task's 
partition) is made in the Executive's dynamic storage region. This 
copy is then used by the Executive. To access the current information 
in this copy, a task must be privileged and have mapping to the 
Executive. 
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2. A Window Block (WB) exists for each active access to files on 
a mounted volume. Its function is to speed up the process of 
retrieving data items in the file; entries in a WB consist 
mainly of pointers to contiguous areas on the device on which 
the file resides. The driver is not concerned with the WB. 

3. Each uniquely opened file on a mounted volume has an 
associated File Control Block (FCB) . The file system uses 
the FCB to control access to the file. 

4. $DEVHD is a word located in system common (SYSCM) and is the 
other independent entry in the I/O data structure. $DEVHD 
points to a singly linked, unidirectional list of Device 
Control Blocks (DCBs) . Each device type in a system has at 
least one associated DCB. The DCB list is terminated by a 
zero in the link word. 

Linked to each DCB is a Driver Dispatch Table (DDT) , which is 
part of the driver. The DDT contains the addresses of the 
driver's four entry points that the Executive can call. 

5. A key data structure is the Unit Control Block (UCB) . All 
the UCBs associated with a DCB appear in consecutive memory 
locations. During internal processing of an I/O request, 
most drivers set R5 to the address of the related UCB; it is 
by means of pointers in the UCB that other control blocks in 
the data structure are accessed. In particular, the UCB 
contains pointers to the DCB, SCB, VCB, and to the UCB to 
which it may have been redirected. If a Redirect command has 
not been issued for the device-unit, the UCB redirect pointer 
points to the UCB itself. When servicing a request for one 
of its UCBs, the driver is unaware of whether I/O was issued 
directly to its own UCB or to a UCB that had been redirected 
to its UCB. 

6. One Status Control Block (SCB) exists for each controller in 
a system. A unique SCB must exist for each 
controller/device-unit capable of performing parallel I/O. 
The SCB contains the fork-block storage required when a 
driver calls $FORK to transfer itself to the fork processing 
level. The I/O request queue listhead is also contained in 
the SCB. Generally, register R4 contains the address of the 
SCB during processing of an I/O request. 

7. One Volume Control Block (VCB) exists for each mounted volume 
in a system. The VCB maintains volume-dependent control 
information. It contains pointers to the File Control Block 
(FCB) and Window Block (WB) , which control access to the 
volume's index file. (The index file is a file of file 
headers.) The WB for the index file serves the same function 
as the WB for a user file. (See the IAS/RSX-11 I/O 
Operations Reference Manual for more information on the index 
file.) All unique FCBs for a volume form a linked list 
emanating from the index file FCB. This linkage aids in 
keeping file access time short. Further, since the window 
that contains the mapping pointers is variable in length, the 
user can increase file access speed by adding more access 
pointers (greater speed requires more main memory) to 
whatever extent the application requires. 
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2.7.1 Data Structures Summary ^H- 

As the writer of a conventional driver, you do not manipulate the ' 

entire I/O data structure. In fact, you are usually involved only 

with the I/O Packet, the UCB, and the SCB. The entire structure has 

been presented to add depth to your understanding of the I/O system, 

to emphasize the relationships among individual control blocks, and to 

clarify further the role a given driver fulfills in the processing of 

an I/O request. 
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CHAPTER 3 
INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM 



If you want to support an I/O device for which DIGITAL has not 
supplied a driver, you can write your own driver. While we have not 
yet- presented explicit details for writing such a driver, you now have 
enough conceptual information to consider incorporating one of your 
own drivers into your system. As will be seen, many considerations 
for writing a driver are best presented in a discussion of 
incorporating one. 

NOTE 

An alternative approach to writing your 
own device driver may be the CONNECT TO 
INTERRUPT VECTOR directive. Refer to 
the description of the CINT$ directive 
in the RSX-llM Executive Reference 
Manual . For examples of the use of 
CINT$, examine the task-level support 
routines for K-series laboratory 
peripheral modules. 



3.1 OVERVIEW OF USER-WRITTEN DRIVERS 

Incorporating a user-written driver is accomplished by means of the 
standard system generation process. Phase 1 of system generation 
includes queries that condition Phase 2 for the inclusion of 
user-written drivers. Specifically, the query 

ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] : 

if answered affirmatively, results in at least one additional query. 
This query is: 

WHAT IS THE ADDRESS OF THE HIGHEST DEVICE INTERRUPT VECTOR? [O] : 

Phase 1 uses the specified address or 400, whichever is greater, to 
allocate sufficient vector space in the Executive to avoid run-time 
destruction of the system stack and to avoid hardware trapping (which 
occurs when the SP goes below 400) . 

The following two additional queries may also appear (refer to Section 
5.3) : 

IS THE EXECUTIVE ROUTINE $GTWRD REQUIRED? [Y/N] : 
IS THE EXECUTIVE ROUTINE $PTWRD REQUIRED? [Y/N] : 
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NOTE 

These additional queries are suppressed 
when certain standard drivers, which 
require the $GTWRD and $PTWRD routines, 
are included during SYSGEN. 

During the same phase of system generation, there is an additional 
decision you must make on behalf of the driver you are planning to 
incorporate into the system. Your driver, similar to most (but not 
all) DIGITAL supplied drivers, can be resident or loadable. Loadable 
drivers require extra Executive features to support them (for example, 
the MCR/VMR LOAD and UNLOAD commands) . You can choose support for 
loadable drivers by answering in the affirmative the following Phase 1 
system generation question: 

DO YOU WANT LOADABLE DRIVER SUPPORT? [Y/N] : 



3.1.1 Overview of User-Written Driver Code 

When you decide to add a driver to your system, you share 
responsibility for the integrity of the Executive. Errors in your 
driver code can cause a system failure and bring to a halt all user 
service. 

To create the source code to drive a device, you must perform these 
steps: 

1. Thoroughly read and understand this manual. 

2. Familiarize yourself in detail with the physical device and 
its operational characteristics. 

3. Determine the level of support required for the device. 

4. Create the data base source code for the device. 

5. Determine actions to be taken at the five driver entry 
points: 

a. Initiator 

b. Cancel I/O 

c. Timeout 

d. Power fail 

e. Interrupt 

6. Create the driver source code. This code will contain the 
following global symbols (where xx is the 2-character device 
mnemonic) : 

$xxTBL:: address of the driver dispatch table (see 
Section 4.1.2.1) 

$xxINT:: address of the driver interrupt entry point 

$xxINP:: addresses of input and output interrupt 
$xxOUT:: entry points (for full-duplex devices). 
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Loadable drivers have one additional requirement. Either 
within the driver source code itself or in file RSXMC.MAC, 
the conditional assembly symbol LD$xx must be defined. The 
INTSV$ macro (refer to Section 4.3) uses this symbol (and 
others in RSXMC.MAC) to determine if the call to $INTSV 
should be omitted from the driver. 

The symbols used to name interrupt entries are different for 
Error Logging devices. See the RSX-llM/M-PLUS Error Logging 
Reference Manual for information on modifying device drivers 
for error logging. Note that Error Logging must be modified 
to handle user-written drivers. 

The DIGITAL-supplied terminal driver (TTDRV) is treated as a 
special case by VMR LOA[D|, in terms of the naming of its 
interrupt entries. 

When adding a resident driver to the system, you should assemble the 
driver with padding space for possible expansion during the debugging 
process. This padding space is necessary because the system may crash 
upon exiting VMR if the new Executive is larger than the old one (see 
the note in Section 3.4.1.5). For a loadable driver, however, you do 
not need to include padding space in the assembly source. 



3.1.2 Overview of Oser-Written Driver Data Bases 

Of the structures associated with an I/O driver, four require assembly 
source: 

1. The DCB 

2. The UCB(s) 

3. The SCB(s) 

4. The device interrupt vector (assembly source required for 
resident drivers only) 

A single DCB can service multiple UCBs and SCBs. The existence of 
multiple UCBs and SCBs is determined by the actual device subsystem 
being supported by a given driver in your hardware configuration. 
Figures 2-2, 2-3, and 2-4 illustrate possible DCB, UCB, and SCB 
structural relationships. 

Within the DCB, UCBs, and SCBs, only those fields that are static or 
that need initialization must be supplied in your assembly source. 
The following three tables list these required fields. 



I 
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Table 3-1 
Required DCB Fields 



Offset 



D.LNK 

D.UCB 

D.NAM 
D.UNIT 

D.UCBL 
D.DSP 



D.MSK 



D.PCB 



Description 



Link to next DCB. This field is zero if this is the 
last (or only) DCB. If you are incorporating more 
than one user-written driver at one time, then this 
field should point to another DCB in a DCB chain. 

Address of the first word (U.DCB) of the first UCB 
associated with this DCB. 

Two-character ASCII generic device name. 

Highest and lowest logical unit numbers controlled by 
this DCB. 

Length of the UCB (including prefix words, if any) . 
If a given DCB has multiple UCBs, all UCBs must be of 
the same length. 

Address of the driver dispatch table. The dispatch 
table is located within the driver code. This field 
contains a global reference to the label associated 
with this table. The field is if the driver is 
loadable. 

I/O function masks. You must supply bit-by-bit 
mapping for these four I/O function masks. Note that 
the format of the mask words is split into two groups 
of 4 words. Functions 0-15 are covered by the first 
group, and functions 16-31 by the second. 

Address of driver Partition Control Block (PCB) . 
This field is required only if loadable driver 
support is included in the system. It must be 
initialized to 0. 



^IS^B^ 



Offset 



U.LUIC 

U.OWN 

U.DCB 
U.RED 



Table 3-2 
Required UCB Fields 



Description 



Log-on UIC. This field is located at a negative 
offset from the start of the UCB. It is present in 
terminal UCBs on multiuser systems only. 

Owning terminal UCB address. This field is located 
at a negative offset from the start of the UCB. It 
is present on multiuser systems only. 

Backpointer to the associated DCB. 

Redirect pointer — initially contains the address of 
this UCB. 



(continued on next page) 
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Offset 



U.CTL 

U.STS 
U.UNIT 
U.ST2 
U.CWl 

U.CW2 
U . CW3 
U.CW4 
U.SCB 
U . ATT 



Table 3-2 (Cont.) 
Required UCB Fields 



Description 



Control bits that must be established by the driver 
writer with the UCB source. 

Unit status byte. 

Physical unit number serviced by this UCB. 

Unit status byte extension. 



Characteristics word 1, 
(Section 4.1.4.1) applies. 



Standard description 



Driver-dependent. 

Driver-dependent. 

Default buffer size. 

Address of the SCB for this UCB. 

TCB address of attached task (initially 0) 



Table 3-3 
Required SCB Fields 



Offset 



S . LHD 
S.PRI 
S.VCT 
S.ITM 
S.CON 

S.STS 
S.CSR 
S.FRK 
S.MPR 



Description 



I/O Queue listhead. 

Priority of interrupting source. 

Interrupt vector address divided by 4. 

Initial timeout count. 

Controller index (that is, controller number 
multiplied by 2) . 

Controller status. 

Address of control and status register. 

Fork block. 

Mapping register block. Needed only by UNIBUS NPR 
devices running on a PDP-11/70 in extended-addressing 
(22-bit) mode. 
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3.2 USER-WRITTEN RESIDENT DRIVERS 

The general procedure for incorporating a user-written resident driver 
into your system is as follows: 

1. Bootstrap the source disk and run SYSGEN Phase 1. 

2. Bootstrap the object disk. 

3. Create the assembly source for the driver. 

4. Create the assembly source for the driver's data base. 

5. Run SYSGEN Phase 2. 

The following subsections present details of steps 4 and 5 above. 

3.2.1 Creating the Data Base for a Resident Driver 

1. Use UIC [200,200] to create source code for your driver's 
data base on the object disk. 

2. Use USRTB.MAC as the filename and file type of the assembly 
source file. USRTB as a filename is not actually required. 
It is, however, a useful convention — one that you will see 
reflected in the sample dialog in Section 3.2.2. 

3. There is no mandatory ordering of the different control 
blocks in the data base for your resident driver. It is 
suggested that you follow the convention of placing the DCB 
first, followed by the UCB(s), followed by the SCB(s). 
However, it is required that all UCB(s) associated with a 
particular DCB must be contiguous. DIGITAL-supplied RSX-llM 
drivers use this ordering scheme — for examples see the file 
[11,10] SYSTB.MAC, created by Phase 1 of SYSGEN. If you are 
incorporating multiple resident drivers into your system, you 
will have more than one instance of a DCB with UCB(s) and 
SCB(s) . 

4. Initialize the device interrupt vector (refer to Section 
4.1.5 for description of this process). 

5. Use the global label $USRTB:: as the address of your first 
(or only) DCB. This is absolutely required. 



3.2.2 Incorporating a Resident Driver 

During the execution of system generation Phase 2, the query 

*D0 YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N] : 

is posed. If the answer is affirmative, then subsequent dialog guides 
you through the process of adding the driver to the generated system. 
Operations performed include assembly of the driver and its data 
structure, inclusion of the resultant object modules into the 
Executive object module library, and editing of the RSX-llM task-build 
command file. 



ifffi^Bfc 
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The following sample dialog illustrates the addition of a driver for 
device XX. All user responses are underlined. The notation [l,2x] 
indicates that the appropriate UIC is to be substituted: [1,20] for 
an unmapped system and [1,24] for a mapped system. 

>* DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N] :Y 

>* WAS LOADABLE DRIVER SUPPORT SELECTED DURING SYSGEN PHASE 1? [Y/N] :Y 

> SET /UIC=[200,200 ] 

>i 



WE WILL PAUSE WHILE YOU ASSEMBLE YOUR DRIVER (S) AND USRTB 
MODULE. THE EXEC ASSEMBLY PREFIX FILE RSXMC.MAC IS ALREADY 
LOCATED UNDER UIC [200,200]. ASSUMING YOUR DRIVER(S) NAME IS 
XXDRV, WHERE XX IS THE DEVICE NAME (E.G., DK) THE FOLLOWING 
COMMANDS WILL ASSEMBLE THE DRIVER (S) AND THE USRTB MODULE. 



>RUN $MAC 

MAC>XXDRV=[1,1]EXEMC/ML, [ 200 , 200] RSXMC , XXDRV 

MAC>USRTB= [1,1] EXEMC/ML ,[200,200] RSXMC , USRTB 

MAC>"Z 



> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

AT. — PAUSING. TO CONTINUE TYPE "RES ...AT 

>RUN_$MAC 

MAC> XXDRV= [1 , 1] EXEMC/ML ,[200,200] RSXMC , XXDRV 

MAC > USRTB== [1,1] EXEMC/ML, f 200 , 200] RSXMC , USRTB 

MAC>!1Y 

>RES ...AT. 

AT. — CONTINUING 



> 

> 

> 

> 

> 

> 

> 

> SET /UIC=[l,2x] 

>LBR 

LB R> RSX11M/RP= [200,200] XXDRV, USRTB 

LBR>'^Z 



NOW YOU MUST ADD YOUR DRIVER (S) AND USRTB MODULE 

TO THE EXEC OBJECT MODULE LIBRARY. THE FOLLOWING IS AN EXAMPLE: 

LBR>RSX11M/RP= [200, 200] XXDRV, USRTB 
LBR>"Z 



YOU MUST NOW ADD COMMANDS TO INCLUDE YOUR DRIVER (S) AND USRTB 
MODULE INTO THE EXEC BY EDITING THE EXEC TASK BUILD COMMAND FILE. 
TO ADD DRIVER (S) , INSERT COMMANDS OF THE FORM: 

RSXllM/LB: XXDRV 

INTO THE COMMAND FILE IN THE PLACE WHERE THE 

OTHER DRIVERS ARE REFERENCED. XXDRV REPRESENTS THE NAME OF 

YOUR DRIVER (S) . 

NOTE: FOR THOSE DRIVERS WHICH YOU WANT TO BE LOADABLE, 
DO NOT INCLUDE CORRESPONDING COMMANDS TO ADD THEM TO 
THE EXECUTIVE. 

THEN LOCATE THE LINE IN WHICH THE MODULE SYSTB IS 
REFERENCED AND ADD THE ENTRY FOR YOUR 
USRTB MODULE IMMEDIATELY AFTER IT. EG: 

[ 1 , 2x ] RSXllM/LB : LOADR : NULTK : SYSTB : USRTB : SYTAB : INITL 
FINALLY, LOCATE THE LINE: 
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>; 

>; GBLDEF=$USRTB:0 

>; 

>; AND DELETE IT. 

>; 

> EDI RSXBLD.CMD 
[PAGE 1] 
* PL TTDRV 
[l,2x]RSXllM/LB:TTDRV 

*I 

[ 1 , 2x ] RSXllM/LB ; XXDRV 

* PL SYSTB 

[ 1 , 2x ] RSXllM/LB : LOADR : NULTK : SYSTB : SYTAB : INITL 
* C/SYSTB/SYSTB ; USRTB/ 

[ 1 , 2x ] RSXllM/LB : LOADR : NULTK : SYSTB : USRTB : SYTAB : INITL 

*PL $USRTB 

GBLDEF=$USRTB:0 

*D 

*EX 

[EXIT] 

>; 

>; YOUR NON-LOADABLE DRIVERS WILL AUTOMATICALLY BE LINKED 
>; WITH THE EXECUTIVE YOU ARE BUILDING. 

This completes the user-written resident driver section of Phase 2, 
which then continues. 



3.3 USER-WRITTEN LOADABLE DRIVERS 

The procedure for incorporation of a user-written loadable driver 
depends on the nature of the data base associated with the driver. 
The data base for such a driver can be either resident or loadable. 

In deciding whether the data base for your loadable driver will be 
resident or loadable, you should consider the following limitations on 
loadable data bases: 

1. A loadable data base is only loaded once; thereafter it is 
resident until the system is bootstrapped again. The 
UNL[OAD] command does not remove a data base from memory even 
if the data base was loaded with the LOA[D] command. 

2. When installing a loadable driver in memory, the LOA[D] 
command searches first for a resident data base. If it finds 
one, it uses that and ignores the loadable version of the 
data base that may accompany the driver image on disk. 

3. When loading a data base, LOA[D] relocates certain known 
pointers within the control blocks.* If the data base 
requires relocation of additional address pointers beyond the 
standard ones, it cannot be loaded with LOA[D]. It must be 
incorporated into the system as a resident data base by means 
of SYSGEN. 



* The pointers are: (DCB) D.LNK, D.UCB; (UCB) U.DCB, U.RED, U.SCB. 
(SCB) S.LHD+2. Chapter 4 gives details on these and other fields in 
the data base. 
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During debugging of a loadable driver (with loadable data base) , you 
can correct errors in the coding of the driver itself by unloading it, 
modifying, assembling, task-building, and reloading the driver. 
However, if the data base must be replaced, the system must be 
bootstrapped to remove it. You can then modify, assemble, and 
task-build the data base, and reload it along with the (corrected) 
driver. 

The subsections below describe the procedure for incorporation of a 
user-written loadable driver as follows: 

1. Creating the data base for a loadable driver. 

2. Assembling a loadable driver and its data base. 

3. Adding the driver and its data base to the system library. 

4. Task-building a loadable driver. 

5. Lociding a user-written loadable driver. 



3.3.1 Creating the Data Base for a Loadable Driver 

In creating the data base for your loadable driver, you must decide 
whether the data base will be resident or loadable. If you decide 
upon a resident data base, you follow the procedure for creating the 
data base of a resident driver with the exception of initializing the 
device interrupt vector (see Section 3.2.1). If, however, you decide 
upon a loadable data base for your driver, you take the following 
steps; 

1. While both the loadable driver and its data base can be 
contained in the same source module, it is recommended that 
you create separate sources for your driver and its data 
base. If, however, you place both the data base and the 
driver in the same module, you must ensure that, when linked, 
the data base follows the driver code. You can do this by 
physically placing the data base code after the driver code 
or by using .PSECT names to force proper allocation. 

2. A useful convention is to name your data base source xxTAB 
and your driver source xxDRV where xx is the 2-character 
device mnemonic. 

3. Place the DCB first in the assembly source. This is 
absolutely required. In a multiuser protection system, the 
DCI$ must be followed first by the associated UCB(s) and then 
by the SCB(s). All UCB(s) associated with a particular DCB 
must be contiguous. DIGITAL-supplied drivers use this 
ordering scheme — for examples see the file [11,10] SYSTB.MAC 
created by Phase 1 of SYSGEN. Since you are creating a 
loadable data base for a single driver, your source code will 
contain a single DCB with associated UCB(s) and SCB(s). 

4. The global label $xxDAT: : marks the start of your driver's 
data base (the DCB). The global label $xxEND:: marks the 
end of the data base (i.e., immediately following the final 
word of the data base) . These labels are absolutely 
required. xx represents the 2-character device mnemonic. 
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3.3.2 Assembling a Loadable Driver and Its Data Base 

During SYSGEN Phase 2, you can assemble your loadable drivers at the 
same time that you assemble resident drivers. To do this, you would 
use the following command line; 

MAC > xxDRV , xxDRV= [1,1] EXEMC/ML ,[200,200] RSXMC/PA ; 1 , xxDRV 

If you decided upon a resident data base for your loadable driver, 
assembly of the data base during SYSGEN Phase 2 is described in 
Section 3.2.2. If, however, you are using a loadable data base for 
your driver (and assuming that you choose to assemble it at the same 
point during SYSGEN Phase 2), use the following input to MAC: 

MAC>xxTAB,xxTAB=[ 1,1] EXEMC/ML, [200 , 200] RSXMC/PA; 1 ,xxTAB 



3.3.3 Adding the Driver and Its Data Base to the System Library 

If you are using a resident data base for your driver, the data base 
is added to the Executive object module library during SYSGEN Phase 2. 
For loadable data bases, however, you use the following command to add 
both the driver and its data base to the same library: 

LBR>RSX11M/RP = [ 200 , 200] xxDRV, xxTAB 



3.3.4 Task-Building a Loadable Driver 

In this section, two examples of task-building a loadable driver with 
a loadable data base are presented:; one for a mapped system and one 
for an unmapped system. 

3.3.4.1 Task-Building a Loadable Driver on a Mapped System - The 
following seven requirements apply to task-building any loadable 
driver, whether user-written or DIGITAL-supplied . 

1. You must specify a task-image filename and a symbol- 
definition filename as TKB output. Both files must be placed 
in the UFD corresponding to the system UIC that will be in 
effect when the LOA[D] command is issued. The filenames must 
both be xxDRV, where xx is the device mnemonic; The Task 
Builder produces output files named xxDRV.TSK and xxDRV.STB. 
For example, the beginning of input to TKB to build a 
paper-tape reader driver for a mapped system might look like 
this (user input underlined) : 

> TKB 

TKB> [1,54] PRDRV/-HD/-MM ,,[1,54] PRDRV= 

t t t t 

Task image. Switches: see Symbol 

items 2 & 3 definition, 
below. 

2. You must not have a task header. Use the switch /-HD, as in 
the example above. A driver is not really a task, but an 
extension of the Executive, and as such needs no task header. 



iii%. 



3-10 



INCORPORATING USER-WRITTEN DRIVERS INTO RSX-llM 

3. You must use the /-MM switch, whether in fact the driver is 
destined for a mapped or an unmapped system. 

4. You must link to the system symbol-table file that contains 
definitions of Executive global symbols. Continuing the 
paper-tape reader driver example from Item 1 above, further 
TKB input might look like this: 

TKB> [ 1,24]RSX11M/LB!PRDRV;PRTAB 
TKB> [ 1,54]RSX11M.STB/SS 

The first line above specifies the library file (/LB) in 
which the input driver object module and the object file for 
the loadable data base can be found. The object module 
specification for the driver must always precede the 
specification for the data base in the TKB command line. 

You omit the data-base file specifier when task-building any 
DIGITAL-supplied driver or one of your own drivers if it has 
a resident data base. All DIGITAL-supplied drivers that are 
declared loadable at SYSGEN use resident data bases. 

The second line in item 4, above, indicates that the 
symbol-table file RSXllM.STB is to be searched selectively 
(/SS) for definitions of Executive global symbols. Note that 
the /SS switch must appear in this context. It cannot be 
omitted. 

5. You must link to the system library file that defines masks 
and offsets used in the Executive. Continuing the example: 

TKB> [1,1]EXELIB/LB 
TKB>7 

The single slash begins the option phase of the Task Builder. 

6. You must direct the Task Builder not to allocate space for a 
stack within the driver: 

TKB>STACK=0 

7. You must specify a partition for the driver. The 
specification differs for mapped and unmapped systems. 
Continuing the mapped-system example: 

TKB>P AR=DRVPAR; 120000: 4000 

TKB>// 

> 

On mapped systems the starting address of the partition must 
be 120000 octal. That is, the loadable driver must be mapped 
to kernel APRS. 

On unmapped systems, the second parameter must be the 
physical starting address of the partition. 

On either mapped or unmapped systems the length of the 
partition may not exceed 4K words (20000 octal bytes) . 
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3.3.4.2 Task-Building a Loadable Driver on an Onmapped System - In 
the example below, we build a magtape driver for an unmapped system. 
The only differences from the mapped-system example are the partition 
starting address and the UIC of some of the files ([1,50] and [1,20] 
instead of [1,54] and [1,24]). 

> TKB 

TKB> [1,50] MTDRV/-HD/-MM ,,[1,50] MTDRV= 

TKB> [ 1 , 2 ] RSXl IM/LB ; MTDRV ; MTTAB 

TKB> [TTSO] RSXllM. STB/SS 

TKB> [1,1]EXELIB/LB 

TKB>/ 

ENTER OPTIONS;^ 

TKB> STACK=0 

TKB> PAR=DRVPAR; 34000; 4000 

TKB>// 

> 



3.3.5 Loading a User-Written Loadable Driver 

Loading is done by using the privileged MCR command LOA[D] . Its form 
is: 

LOA[D] xx: [/PAR=partition] 

where xx is the 2-character device mnemonic. Specifying a partition 
is optional. If none is specified, the partition input to the Task 
Builder is used. 

The LOA[D] command requires that the two files xxDRV.TSK and xxDRV.STB 
reside under the system UIC (i.e., the UIC established by the SET 
/SYSUIC command). Typically, this UIC is [1,50] for unmapped systems 
and [1,54] for mapped systems. 

LOA[D] searches first for a resident data base for the driver being 
loaded. If none is found, LOA[D] looks for the following global 
symbols in the file xxDRV.STB: 

$xxDAT:: address of the start of the data base (the DCB) 
associated with the driver 

$xxEND:: address+2 of the last word of the data base 
associated with the driver. 



3.4 DRIVER DEBUGGING 

Because the protection checks provided for user programs are not 
available to system modules, driver errors are more difficult to 
isolate than user-program errors. But conventional drivers, because 
they are modular and short, should be easily debugged. This debugging 
process requires that you understand the following topics, each of 
which is discussed in a separate subsection: 

1. Debugging aids and tools. 

2. Fault isolation. 

3. Fault tracing 

4. Rebuilding and reincorporating a driver. 
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3.4.1 Debagging Aids 

Adding a user-written driver carries with it the risk of introducing 
obscure bugs into an RSX-llM system. Since the driver runs as part of 
the Executive, special debugging tools are both desirable and 
necessary. RSX-ilM provides several such aids, which can be 
incorporated into your system during SYSGEN: 

1. Executive stack and register dump 

2. XDT 

3. Panic dump 

4. Crash dump analysis (CDA) support routine. 

You need not select any of this software during SYSGEN. If, however, 

you do require the facilities they offer, you can select from one to 

three of them for incorporation in your system (panic dump and the CDA 

support routine are mutually exclusive) . The following subsections 

describe the features and use of each debugging aid. 



3.4.1.1 Executive Stack and Register Dump Routine - At SYSGEN, you 
can indicate that you want a dump of the Executive stack and the 
registers when a crash occurs. This dump will be provided in the 
following manner: 

1. A system error, or the XDT X command (described in the next 
section) , or operator manipulation of the switch register 
following a halt causes processing to resume at location 
40(8) . 

2. Location 40(8) contains a JMP to location $CRASH. 

3. $CRASH invokes the routine that dumps the Executive stack and 
registers as shown below: 

SYSTEM CRASH AT LOCATION 047622 

REGISTERS 
R0=000340 Rl=177753 R2=000353 R3=000000 
R4=000004 R5=046712 SP=000472 PS=000340 

SYSTEM STACK DUMP 

LOCATION CONTENTS 

000472 000004 

000474 000000 

000476 001514 

000500 000340 

000502 177753 

000504 000353 

000506 000000 

000510 000000 

000512 057750 

000514 002504 

000516 030011 

000520 100340 

000522 000340 
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LOCATION CONTENTS 

000524 056446 

000526 000000 

000530 102144 

000532 000000 

000534 101376 

000536 101372 

000540 102022 

000542 170000 

Following this display, either the CDA support routine or panic dump 
is invoked — if either is present in the system. Otherwise, the 
system halts. ' 



3.4.1.2 XDT - The Executive Debugging Tool - An interactive debugging 

tool has been developed for RSX-llM to aid in debugging Executive 

modules, I/O drivers, and interrupt service routines. This debugging 

aid, called XDT, is a version of RSX-11 ODT. XDT does not contain the ^Blt, 

following features and commands available on ODT: '' 

No $M - (Mask) register 

No $X - (Entry Flag) registers 

No $V - (SST vector) registers 

No $D - (I/O LUN) registers 

No $E - (SST data) registers ^gfttt, 

No $W - (Directive status word) $DSW word 

No E - (Effective Address Search) command 

No F - (Fill Memory) command 

No N - (Not word search) command 

No V - (Restore SST vectors) command 

No W - (Memory word search) command 

In addition, the X (Exit) ODT command has been changed for XDT. The X 
command causes a jump to the crash reporting routine. 

Except for the omitted features and the change in the X command, XDT 
is command-compatible with RSX-11 ODT; consequently, the RSX-11 ODT 
Manual can be used as a guide to XDT operation. 

XDT may be included in a system during Phase 1 of system generation. 
The query: 

DO YOU WANT TO INCLUDE THE EXECUTIVE DEBUGGING TOOL? [Y/N] : 

is posed. If the answer is affirmative, then XDT is automatically 
included in the generated system. When the resultant system is 
bootstrapped, XDT gains control and types on the console terminal: 

XDT: <system version> 

followed by the prompting symbol 

XDT> 

3-14 






INCORPORATING OSER-WRITTEN DRIVERS INTO RSX-llM 

You can set breakpoints at this time, and then give a G command, 
passing control to the RSX-llM Executive initialization code. 
Whenever control reaches a breakpoint, a printout similar to that of 
RSX-11 ODT occurs. 

A forced entry to XDT can be executed at any time from a privileged 
terminal by means of the MCR Breakpoint (BRK) command. Thus, the 
normal procedure is to type G when the system is bootstrapped without 
setting any breakpoints. When it becomes necessary to use XDT, the 
MCR Breakpoint command is executed, causing a forced breakpoint. XDT 
then prints on the console terminal: 

BE:xxxxxx 

followed by the prompting symbol 

XDT> 

You can then set breakpoints and/or issue other XDT commands. 
Continue system operation by typing the P (Proceed) command to XDT. 

Note that XDT runs entirely at priority level 7 and does not interfere 
with user-level RSX-11 ODT. In other words, user-level RSX-11 ODT can 
be in use with several tasks, while XDT is being used to debug 
Executive modules. 

All XDT command I/O goes to and from the console terminal, and the L 
(List Memory) command can list on either the console or the line 
printer . 

Using XDT to debug a loadable driver on a mapped system has special 
pitfalls. One problem that can arise is a T-bit error: 

TE:xxxxxx 
XDT> 

This error results when control reaches a breakpoint that you have 
set, using XDT, in a loaded driver on a mapped system. The T-bit 
error, rather than the expected BE: error, occurs unless register 
APRS is mapped to the driver at the time XDT sets the breakpoint. 

To avoid this T-bit error, assemble the driver with an embedded BPT 
instruction or use either the ZAP utility or the MCR OPEN function to 
set the breakpoint by replacing a word of code with the BPT 
instruction. When control reaches a breakpoint set in this manner, 
XDT prints: 

BE:xxxxxx 
XDT> 

Recover as follows: using XDT, replace the BPT instruction with the 
desired instruction. Decrement the PC by subtracting 2 from the 
contents of register R7. Then proceed by using the P or S commands. 

NOTE 

You should not set breakpoints in more 
than one module that maps into the 
Executive through APR 5 or APR 6. In 
particular, do not set breakpoints in 
more than one loadable driver at a time 
or XDT will overwrite words of main 
memory when it attempts to restore the 
contents of breakpoints. 
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3.4.1.3 Panic Dump - The Panic Dump routine (PANIC) saves registers 
RO through R6 and then halts, awaiting dump limits to be entered. 

The procedure for entering dump limits depends on whether or not your 
processor has a console switch register. The subsections that follow 
describe the procedure in each instance. 



3.4.1.3.1 Using PANIC on Processors with Console Switch 
Registers - For processors with console switch registers, you can 
obtain dumps of selected blocks of memory by using the following 
procedure: 



Enter the low dump limit in the console switch register 
press CONT. The processor will immediately halt again. 



and 



Enter the high dump limit in the console switch register and 
press CONT. The dump will begin on the device whose CSR 
address is D$$BUG (usually 177514, which is the line 
printer) . The actual value of D$$BUG is determined during 
system generation when answering the panic dump question. At 
the end of the dump, the processor will again halt, awaiting 
the input of another set of dump limits. 

If your system does not have the Executive routine stack and 
register dump, enter the dump limits 0-520(8) when the Panic 
Dump routine first halts. This causes dump of the system 
stack and the general registers. The limit 520(8) changes if 
the highest interrupt vector is above 400(8). The actual 
upper limit is always the value of the global symbol $STACK 
and can be obtained from the global symbol listing in the 
Executive memory allocation map. 



3.4.1.3.2 Using PANIC on Processors Without Console Switch 
Registers - A number of PDP-11 processors are being delivered without 
a console switch register; they are configured with the M9301 Console 
Emulator and Bootstrap. This presents no problem for the normal 
operation of RSX-llM, because it does not require a switch register. 
However, the panic dump routine usually reads its arguments from the 
switch register. In systems that have been generated for processors 
that have no switch register, the panic dump module has been altered 
to read its arguments from location 0. The following instructions are 
designed to allow you to enter the proper information to the panic 
dump routine on processors equipped with the M9301 Console Emulator. 



1. When PANIC halts, the RUN light will go out. 
press and release the BOOT switch. 

The Console Emulator should display: 

XXXXXX XXXXXX XXXXXX nnnnnn 
$ 



Where nnnnnn is the address+2 of the HALT instruction, 

You should enter the following: 

$L 0<CR> 

$D low-address<CR> 

$L nnnnnn<CR> 

$S <CR> 



At this time 
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3. The processor should again halt. Press and release the BOOT 
switch. 

The Console Emulator should display: 

XXXXXX XXXXXX XXXXXX mmmmmm 
$ 

4. You should then enter: 

$L 0<CR> 

$D high-address<CR> 

$L mmmmmm <CR> 

$S <CR> 

At this time the dump should commence. When it is finished, the 
processor will halt and wait for additional input. 



3.4.1.3.3 Sample Output from Panic Dump - A portion of the output 
from Panic Dump is shown below. Output is in 3-line groupings. In 
the left-hand column, two addresses are shown. The first address is 
the absolute address; the second address is the dump relative 
address. The first line in a 3-line group gives the octal word value; 
the second line gives the two octal byte values of the word; the 
third line contains the ASCII representation of the bytes. The ASCII 
representations in each word are reversed to improve readability. The 
first output grouping from Panic Dump shows, proceeding from right to 
left, PS, RO, Rl, R2, R3 , R4 , R5, and the SP. 

000544 000000 046076 000066 000000 000000 000000 000000 045316 
000000 000 000 114 076 000 066 000 000 000 000 000 000 000 000 112 316 

"@ "e > L 6 "^e "@ "& "e "@ "@ "@ ""^ "@ n j 

000000 022646 000340 045770 000340 045770 000340 045770 000340 
000000 045 246 000 340 113 370 000 340 113 370 000 340 113 370 000 340 
& % -^e K "§ K '^@ K "@ 

000020 045776 000340 011124 000340 045770 000340 050500 000340 
000020 113 376 000 340 022 124 000 340 113 370 000 340 121 100 000 340 
K "^T^R "@ K "OSQ "19 

000040 000167 000543 000001 000001 000000 000000 000000 000353 
000040 000 167 001 143 000 001 000 001 000 000 000 000 000 000 000 353 

"§ "A "A "§ ""A "§ "§ "& "@ "@ "0 "e "@ 

000060 035444 000340 034034 000340 032776 000340 032402 000340 
000060 073 044 000 340 070 034 000 340 065 376 000 340 065 002 000 340 
$ ; '^0 "X 8 '@ 5 "@ "B 5 "e 



3.4.1.4 Crash Dump Analysis Support Routine - The crash dump analysis 
(CDA) support routine, when entered, prints the following message on a 
notification device specified at SYSGEN: 

CRASH - CONT WITH SCRATCH MEDIA ON device mnemonic 
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You can then put the secondary crash dump device on-line and depress 
the CONT switch on the operator's console. The Executive Crash Dump 
routine will dump memory to the crash dump device and halt the 
processor upon completion. 

The procedure for subsequently invoking the Crash Dump Analyzer, which 
reads and formats the memory dump, is fully documented in the RSX-llM 
Crash Dump Analyzer Reference Manual. 



3.4.2 Fault Isolation 

Four causes can be identified when the system faults: 

1. A user-state task has faulted in such a way that it causes 
the system to fault. 

2. The user-written driver has faulted in such a way that it 
causes the system to fault. 

3. The RSX-llM system software itself has faulted. 

4. The host hardware has faulted. 

When the system faults, you must immediately determine which of these 
four causes is responsible. In this section we present some 
procedures that can help you isolate the source of the fault. 
Correcting the fault itself is your responsibility. 



3.4.2.1 Immediate Servicing - Faults manifest themselves in roughly 
four ways (they are listed here in order of increasing difficulty of 
isolation) : 

1. If XDT is included, an unintended trap to XDT occurs. 

2. The system displays text indicating a crash has occurred and 
halts. 

3. The system halts but displays nothing. 

4. The system is in an unintended loop. 

The following discussions assume the existence of a system built with 
at least one of the debugging aids described in Section 3.4.1. (Note 
that the minimal system does not have space for these routines.) 

The immediate aim, regardless of the fault manifestation, is to get to 
the point where you can obtain pertinent fault isolation data. 

Case 1 — The system has trapped to XDT: 

The trap may or may not be intended (for example, a previously set 
breakpoint). If it is not intended, type the X command, causing XDT 
to exit to location 40(8), from which the Executive stack and register 
dump routine (if present) followed by either Panic Dump or the CDA 
support routine (if present) will be invoked. If, however, you have 
some idea of the source of the problem (for example, a recent coding 
change) , then you may use XDT to examine pertinent data structures and 
code. 
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Case 2 — The system has displayed text indicating a crash has occurred: 

If the text consists of output from the Executive stack and register 
dump routine (refer to Section 3.4.1.1), all the basic information 
describing the state of the system has been displayed. If the text 
has been produced by the CDA support routine, follow the procedure for 
obtaining and formatting a memory dump as outlined in the RSX-11 Crash 
Dump Analyzer Reference Manual . 

Case 3 — The system has halted but displays no information: 

Before taking any action, preserve the current PS and PC and the 
pertinent device registers (that is, examine and record the 
information these registers contain) . The procedure depends on the 
particular PDP-11 processor. Consult the appropriate PDP-11 Processor 
Handbook for details. 

After preserving the PS and PC, invoke your resident debugging aid: 
enter 40(8) in the switch register, press LOAD ADDR, and then press 
START. The contents of 40(8) cause the successive invocation of: 

1. The Executive stack and register dump routine (if present) . 

2. Either Panic Dump or CDA support routine (if present). 
Case 4 — The system is in an unintended loop: 

Proceed as follows: 

1. Halt the processor. 

2. Record the PC, the PS, and any pertinent device registers, as 
in Case 3 above. 

You may then want to step through a number of instructions in an 
attempt to locate the loop. For this attempt to be meaningful you 
must first disable the system clock. Proceed as follows: Examine the 
contents of word 777546 (if your system has a line-frequency clock) or 
word 772540 (if a programmable clock) . Clear bit 6 in this word and 
redeposit the word. Note: the system will not run until you have 
reenabled the clock. 

After trying to locate the loop and reenabling the clock, transfer to 
location 40(8) as in Case 3. 

This brings us to an equivalent status for the four fault situations. 



3.4.2.2 Pertinent Fault Isolation Data - Before you attempt to locate 
the fault, we strongly advise you to dump system common (SYSCM) . 
SYSCM contains a number of critical pointers and listheads. Find the 
appropriate limits for the module SYSCM by examining the Executive 
memory allocation map. Enter these limits to the Panic Dump routine 
or specify them in the command line used to invoke the Crash Dump 
Analyzer . 

In addition, we advise you to dump the dynamic storage region and the 
device tables. The dynamic storage region is the module INITL and any 
additional space gained from the SET /POOL command and the device 
tables are in SYSTB. 
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At this point, you have the following data: 

PS 

PC 

The Stack 

RO through R6 

Pertinent device registers 

The dynamic storage region 

The device tables 

System common 

These data represent a minimal requirement for effectively tracing the 
fault. 



3.4.3 Fault Tracing 

Three pointers in SYSCM are critical in fault tracing. These pointers 
are described below: 

$STKDP - Stack Depth Indicator 

This data item indicates which stack was being used at the time 

of the crash. $STKDP plays an important role in determining the 0lllt, 

origin of a fault. The following values apply: 

+1 — User (task-state) stack 

or less — System stack 

If the stack depth is +1, then the user has crashed the system. 
In a system with brickwall protection (for example, the mapped 
RSX-llM system) , the nonprivileged user should not be able to 
crash the system. 



$TKTCB - Pointer to the Current Task Control Block (TCB) 

This is the TCB of the user-level task in control of the CPU. 

$HEADR - Pointer to the Current Task Header. 

The $HEADR word points to the header of the task currently 
running. The task header provides additional data to help 
isolate a fault. Figures 3-1 and 3-2 show the layout of task 
headers for unmapped and mapped systems, respectively. 

The first word in the header is the user's stack pointer (SP) the 
last time it was saved. If the user branches wildly into the 
Executive, the Executive terminates the user task, but the system 
continues to function (possibly erroneously). Knowing the user's 
stack pointer provides one more link in the chain that may lead 
to the resolution of the fault. 

The header (as pointed to by $HEADR) also contains the last-saved 
register set, just before the header guard word (the last word in 
the header — pointed to by H.GARD) ,. 
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H.NLUN 
H.GARD 



H.HDLN 



RO 



R1 



R2 



R3 



• 




PS 


• 


PC 


Length in bytes 


R5 


SP 


R4 





Figure 3-1 Task Header on an Unmapped System 



H.NLUN 
H.GARD 



RO 



R5 



PC 



PS 



H.HDLN 



Length in bytes 



Figure 3-2 Task Header on a Mapped System 
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3.4.3.1 Tracing Faults Using the Executive Stack and Register 

Dump - To trace a fault after a display of the Executive stack and 
register contents, first examine the system stack pointer. Usually an 
Executive failure is the result of an SST-type trap within the 
Executive. If an SST does occur within the Executive, then the origin 
of the call on the crash-reporting routine is in the SST service 
module. (The crash call is initiated by issuing an lOT at a stack 
depth of zero or less.) 



Jl% 



A call to crash also occurs in the Directive Dispatcher when an EMT is 

issued at a stack depth of zero or less, or a trap instruction is 

executed at a stack depth of less than zero. The stack structure in 
the case of an internal SST fault is shown in Figure 3-3. 



PS 



PC 



R5 



R4 



R3 



R2 



R1 



RO 



Return to system exit 



Zero or more SST parameters 



SST fault code 



Number of bytes 



■SP 



Figure 3-3 Stack Structure: Internal SST Fault 



The fault codes are: 





2 

4 

6 

10 

12 

14 

16 

20 

22 

24 

26 

30 

32 

34 



ODD ADDRESS AND TRAPS TO 4 

MEMORY PROTECT VIOLATION 

BREAK POINT OR TRACE TRAP 

lOT INSTRUCTION 

ILLEGAL OR RESERVED INSTRUCTION 

NON RSX EMT INSTRUCTION 

TRAP INSTRUCTION 

11/40 FLOATING POINT EXCEPTION 

SST ABORT-BAD STACK 

AST ABORT-BAD STACK 

ABORT VIA DIRECTIVE 

TASK LOAD READ FAILURE 

TASK CHECKPOINT READ FAILURE 

TASK EXIT WITH OUTSTANDING I/O 

TASK MEMORY PARITY ERROR 



0r^^^^St 
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The PC points to the instruction following the one that caused the SST 
failure. The number of bytes is the number normally transferred to 
the user stack when the particular type of SST occurs. If the number 
is 4, then a non-normal SST fault occurred, and only the PS and PC are 
transferred. There are no SST parameters. 

If the failure is detected in $DRDSP, the stack is the same as shown 
in Figure 3-3, except that the number of bytes, the SST fault code 
(the fault codes are listed above) , and the SST parameters are not 
present. The crash report message, however, will indicate that the 
failure occurred in $DRDSP. 

One SST-type fa; 
structure of Fi 

establish the StaCK sttuutULe; um-ti >jaii ue ucuuvjcu ujc uiic vcixuc vyj. 

the SP and the contents of the top word on the stack. If the stack 
structure is that of Figure 3-3, then the failure occurred in $DRDSP, 
or was a normal SST crash. If the stack structure is that of Figure 
3-4, then an abnormal SST crash has occurred. 




SP 



PS 



PC 



Figure 3-4 Stack Structure: Abnormal SST Fault 

Abnormal SST failures occur when it is not possible to push 
information on the stack without forcing another SST fault. When this 
situation occurs, a direct jump to the crash-reporting routine is made 
rather than an lOT crash. The PS and PC on the stack are those of the 
actual crash, and the address printed out by the crash-reporting 
routine is the address of the fault rather than the address of the lOT 
that crashes the system. Note that the crash-reporting routine 
removes the PC and PS of the lOT instruction from the stack, which in 
this case is incorrect. Thus, the SP appears to be 4 bytes greater 
than it really is (as in Figure 3-4) . 

You now have all the information needed to isolate the cause of the 
failure. From this point on, rely on personal experience and a 
knowledge of the interaction between the driver and the services 
provided by the Executive. 



3.4.3.2 Trcicing Faults When the Processor Halts Without Display - To 

trace a fault when the processor halts but displays no information 
(case 3 in Section 3.4.2.1 above), first examine $STKDP, $TKTCB, and 
$HEADR. The difficulty in tracing failures in this case is that the 
system stack is not directly associated with the cause of a failure. 

By examining $STKDP, you can determine the system state at the time of 
failure. if it was in user state, the next step is to examine the 
user's stack. The examination focuses on scanning the stack for 
addresses that may be subroutine links that can ultimately lead to a 
thread of events isolating the fault. This is essentially the aim of 
looking at the system stack if $STKDP is zero or less. 
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Frequently, a fault can occur that causes the SP to point to Top of 
Stack (T0S)+4. This fault results from issuing an RTI when the top 
two items on the stack are data. The result is a wild branch and 
then, most probably, a halt. Figure 3-5 shows a case in which two 
data items are on the stack when the program executes an RTI. TOS 
points to a word containing 40100. Suppose that location 40100 
contains a halt. This indicates that the original SP was four bytes 
below the final SP, and fault tracing should begin from the original 
SP. 



^H^^a^ 



40100 



•SP 



■SP 



Figure 3-5 Stack Structure: Data Items on Stack 



This type of fault also occurs when an RTS instruction is executed 
with an inconsistent stack. However, in that case, SP points to 
TOS+2. 

A scan of the contents of the general registers may give some hint as 
to the neighborhood in which a fault (or the sequence of events 
leading up to the fault) occurred. 

If the fault occurred in a new driver, a frequent source of clues is 
the buffer address and count words in the UCB (U.BUF, U.BUF+2, U.CNT) , 
as are the activity flags (US.BSY and S.STS) . Other locations in both 
the UCB and SCB may also provide information that may help locate the 
source of the fault. 



3.4.3.3 Tracing Faults After an Unintended Loop - To trace a 
when an unintended loop has occurred, first halt the processor. 



fault 



After you halt the processor, the same state exists as was discussed 
in Section 3.4.3.2. Follow the same tracing procedure described 
there. A specific suggestion is to check for a stack overflow loop. 
Patterns of data successively duplicated on the stack indicate a stack 
looping failure. 



jfK^pk. 



3.4.3.4 Additional Hints for Tracing Faults - Another item to check 
is the current (or last) I/O Packet, the address of which is found in 
S.PKT of the SCB. The packet function (I.FCN) defines the last 
activity performed on the unit. 



If trouble occurred in terminating an I/O 
system dynamic memory region may provide 
starts at the address contained in $CRAVL, a 
all I/O packets are built in system dynam 
returned to the dynamic memory region whe 
terminated. Following the link pointers 
whether I/O completion proceeded to that poi 
optimization, $PKAVL (SYSCM) points to 
blocks of dynamic memory that are not linked 



request, a scan of the 
some insight. This region 

cell in SYSCM. Because 
ic memory, their memory is 
n they are successfully 

in this region may reveal 
nt. In systems with QIO 
a list of I/O packet-sized 

into the $CRAVL chain. 



jHW^^m 
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A frequent error for an interrupt-dr iven device is to terminate an I/O 
Packet twice when the device is not properly disabled on I/O 
completion and an unexpected interrupt occurs. This action ultimately 
produces a double deallocation of the same packet of dynamic memory. 
Double deallocation of a dynamic buffer in RSX-llM causes a loop in 
the module $DEACB on the next deallocation (of a block of higher 
address) after the second deallocation of the same block. At that 
time, R2 and R3 both contain the address of the I/O Packet memory that 
has been doubly deallocated. If XDT has been included in the system, 
the deallocation routine checks for bad deallocation and crashes the 
system if it occurs. 



3.4.4 Rebuilding and Reincorporating a Driver 

The procedure for rebuilding and reincorporating a driver into your 
system depends on whether the driver is resident or loadable. The two 
subsections that follow describe the procedure for each kind of 
driver . 



3.4.4.1 Rebuilding and Reincorporating a Resident Driver - The 
procedure for rebuilding and reincorporating a resident driver 
involves five steps: 

1. Correct and assemble the driver and/or device data 
structures. 

Assuming that the object system has been bootstrapped, 
appropriate volumes have been MOUnted , and the source code 
for the user driver and/or device data base has been updated, 
then the following commands effect the reassembly of both the 
driver and the data base: 

> SET /UIC=[200,200] 

> RUN $MAC ! OR RUN $BIGMAC 

MAC > XXDRV=[1,1]EXEMC/ML, [ 200 , 200] RSXMC/PA: 1 ,XXDRV 

MAC > USRTB=[1,1]EXEMC/ML, [ 200 , 200] RSXMC/PA; 1 , USRTB 

MAO^^Z 

2. Update the Executive object module library. 

After reassembling the user driver and/or data base, you must 
update the Executive object module library. The following 
commands will accomplish this: 

>SE T /UIC=[l,2x] 

> RUN $LBR 

LBR> RSX11M/RP= [200,200] XXDRV, USRTB 

LBR>^^1 

3. Rebuild the Executive. 

Because an updated driver is to be reinserted into the 
system, the Executive, of which the driver is a part, must be 
relinked. The following commands are an example of this 
relinking : 
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> SET /UIC=[l,2x] 

OR RUN $BIGTKB 



>RUN 


$TKB 


! 


TKB>@RSXBLD 
TKB>lZ 

>SET /UIC=[1 


5x] 



> RUN $PIP 

PIP> RSX11M.SYS/NV=RSX11M.TSK 

PIP>2Z 

4. Incorporate tasks into the system using Virtual MCR. 

Run Virtual MCR (VMR) to incorporate tasks into the system. 
This step in the procedure requires that you: 






Establish system partitions 

Release all unused space to the dynamic storage 
region 

Install tasks (at least FCP, INS, MOU, and MCR) 

Exit from Virtual MCR 



The following is an example of this step: 

> RUN $VMR/UIC=[l,5x] ! RUN VIRTUAL MCR 

ENTER FILENAME ; RSX11M. SYS ! VMR PROMPTS FOR FILE NAME 
VMR> SET /MAIN=SYSPAR;1300:1Q0:TASK ! SET UP SYSTEM PARTITION 
VMR> SET /MAIN=PAR14K: 400; 700; TASK ! SET UP 14K PARTITION 
VMR>SET /SUB=PAR14K;GEN;400:400 ! SET UP 8K SUB PARTITION 



VMR> SET /POOL=400 



VMR>INS 


BOO 


VMR>INS 


DM0 


VMR>INS 


FCPNMH 


VMR>INS 


IND 


VMR>INS 


INI 


VMR>INS 


INS 


VMR>INS 


MCR 


VMR>INS 


MOU 


VMR>INS 


SAV 


VMR>INS 


TKN 


VMR>INS 

■X 


UFD 



VMR> Z 



ADD FREE SPACE TO POOL 

INSTALL BOOT 

INSTALL DISMOUNT 

INSTALL PILE SYSTEM 

INSTALL INDIRECT FILE PROCESSOR 

INSTALL INITVOLUME 

INSTALL INSTALL 

INSTALL MCR 

INSTALL MOUNT 

INSTALL SAVE 

INSTALL TASK TERMINATION TASK 

INSTALL USER FILE DIRECTORY BUILDER 

EXIT FROM VIRTUAL MCR 



The eleven INStall commands above can be placed in an 
indirect VMR file by Phase 2 of SYSGEN. Instead of entering 
each command, you could then enter, for example, the 
following; 

@ [200,200] INSTALL 

Bootstrap the new system. 

The new system can now be bootstrapped with the MCR BOOt 
command. If you are using the baseline system, first issue 
the following command: 

> INS B00;-1 

Then issue the following command: 

>B00 [l,5x]RSXllM 
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NOTE 

If the newly created Executive is larger 
or smaller than the old one, the system 
may not run properly after exiting VMR. 
In this case the procedure outlined 
above amounts to supporting two systems 
on the same volume. See the RSX-llM 
System Generation Manual for the 
procedure to follow to support multiple 
systems on one volume. 



3.4.4.2 Rebuilding and Reincorporating a Loadable Driver - A loadable 
driver is easier to reincorporate during debugging than a resident 
driver. After correcting and assembling the driver source, simply 
unload the old version, using the MCR command UNL, task-build the new 
one, and load it using the LOA command. 

The data structure, once loaded, becomes a permanent part of the 
Executive. It is not removed by the UNL command. If the data 
structure is in error and cannot be patched, correct its source, 
reassemble, and task-build it. Then bootstrap the system before 
loading the corrected driver. 
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CHAPTER 4 
WRITING AN I/O DRIVER — PROGRAMMING SPECIFICS 

In Chapter 2, overviews were given for: 

Data structures; 

Executive services, and 

Programming protocol. 

This chapter gives details for the data structures, and in addition 
discusses specifics of multicontroller drivers and the INTSV$ macro. 
Executive services are covered in Chapter 5. The protocol coverage in 
the discussion of programming protocol in Chapter 2 is detailed enough 
to make further elaboration unnecessary. 

4.1 DATA STRUCTURES 

The following elements in the I/O data structure are of concern to the 
programmer writing a driver: 

1. The I/O packet 

2. The DCB 

3. The UCB 

4. The SCB 

5. The device interrupt vector 

The I/O data structure, and the first four control blocks listed above 
in particular, contain an abundance of data pertaining to input/output 
operations. Drivers themselves are involved with only a subset of the 
data. 

In the detailed descriptions of the I/O packet, the DCB, the UCB, and 
the SCB that follow, most data fields (words or bytes) are classified 
by one of five descriptions. Two items in each description indicate: 

• Whether the field is initialized in the data-structure 
source, and 

• What sort of access the driver has to the field during 
execution. 



4-1 



WRITING AN I/O DRIVER—PROGRAMMING SPECIFICS 

The five descriptions are: ^^ 

<initialized, not referenced> 

Field is supplied in the data-structure source code, and is 
not referenced by the driver during execution. 

<initialized, read-onlY> 

Field is supplied in the data-structure source code, and may 
be read by the driver. 

<not initialized, read-only> 

Either an agent other than the driver establishes this field, 
or the driver sets it up once, and thereafter references it 
read-only. 

<not initialized, read-write> 

Either the driver or some other agent establishes this field, 
and the driver may read it or write over it. 

<not initialized, not referenced> 

Field does not involve the driver in any way. 011$^^ 

These five descriptions cover most of the fields in the four control 
blocks described in this section. Exceptions are noted in the text. 

The final discussion in this section deals with the device interrupt 
vector . 



4.1.1 The I/O Packet 

Figure 4-1 shows the layout of the 18-word I/O Packet, which is 
constructed and placed in the driver I/O queue by QIC directive 
processing, and is subsequently delivered to the driver by a call to 
$GTPKT. The DPB from which the I/O Packet is generated is illustrated 
in Figure 4-2 (see Section 4.1.1.2). 



4.1.1.1 I/O Packet Details - The I/O Packet is built dynamically by 
QIO directive processing. Thus, no static fields exist with respect 
to a driver. I/O Packets are created dynamically, and therefore the 
first parameter (I.LNK) does not apply. Fields in the I/O Packet 
(described below) are classified as: 

Not referenced, 
read-only, or 
read-write. 

I.LNK 

Driver access: 

Not referenced. 

Description: 

Links I/O Packets queued for a driver. A zero ends the 
chain. The listhead is in the SCB (S.LHD) . 
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I.EFN 



Driver access;; 

Not referenced. 

Description: 

Contains the event flag number as copied by QIO directive 
processing from the requester's DPB. 



I.LNK 


Link to next I/O packet 





I.PRI ) 
I.EFN f 


EFN 


PRI 


2 


I.TCB 


TCB address of requester 


4 


I.LN2 


Address of second LUT word 


6 


I.UCB 


Address of redirect UCB 


10 


I.FCIM 


Function code 


Modifier 


12 


I.IOSB 


Virtual address of I/O status block 


14 




Relocation bias of lOSB 


16 




Real address of lOSB 


20 


LAST 


Virtual address of AST service routine 


22 


I.PRM 




24 










Device 






parameters 





























I . PRI 



Figure 4-1 I/O Packet Format 



Driver access: 

Not referenced. 
Description: 

Priority copied from the TCB of the requesting task, 
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I . TCB ^/gff^^ 

Driver access: 

Not referenced. 

Description: 

TCB address of the requesting task. 

I.LN2 

Driver access: 

Not referenced. 

Description: 

Contains the address of the second word of the LUT entry in 

the task header to which the I/O request is directed. For 

open files on file-structured devices, this word contains the ^%|, 

address of the Window Block; otherwise, it is zero. 

I.UCB 

Driver access: 

Not referenced. 

Description: 

Contains the address of the unit to which I/O is to be 
directed. I.UCB is the address of the Redirect UCB if the 
starting UCB has been subject to an MCR Redirect command. 

I . FCN 

Driver access; 

Read-only. 

Description: 

Contains the function code (see Table 4-1, Section 4.1.2.2) 
for the I/O request. The modifier byte is one or more 
subf unction bits that may be set. 

I.IOSB 

Driver access: 

Not referenced. 

Description: 

I.IOSB contains the virtual address of the I/O Status Block 
(lOSB) , if one is specified, or zero if one is not specified. 

I.IOSB+2 and I.IOSB+4 contain the address doubleword for the 
lOSB (see Appendix A for a detailed description of the 
address doubleword) . On an unmapped system, the first word 
is zero; the second word is the real address of the lOSB. 



4-4 



WRITING AN I/O DRIVER — PROGRAMMING SPECIFICS 

In a mapped system, the first word contains the relocation 
bias of the lOSB; the bias is, in effect, the number of the 
32-word block in which the lOSB starts. This block number is 
derived by viewing available real memory as a collection of 
32-word blocks numbered consecutively, starting with 0. 
Thus, if the lOSB starts at physical location 3210(8), its 
block number is 32(8). 

The second word is formatted as follows: 

Bits 0-5 Displacement in block (DIB) 
Bits 6-12 All zeros 
Bits 13-15 6 

The displacement in block is the offset from the block base. 
In the above example, in which the lOSB starts at 3210(8), 
the DIB is equal to 10(8). 

The value 6 in bits 13-15 is constant. It is used to cause 
an address reference through Kernel Address Page Register 6 
(APR6) . Again, see Appendix A for details. 

We defer discussion of the address doubleword to an appendix 
because you seldom have to be concerned with its contents or 
format in writing a conventional driver. Its construction 
and subsequent manipulation are normally external to the 
driver. Subroutines are provided as Executive services for 
programmed I/O to render the manipulations of I/O transfers 
transparent to the driver itself. 



LAST 



Driver access: 

Not referenced. 
Description: 

Contains the virtual address of the AST service routine to be 
executed at I/O completion. If no address is specified, the 
field contains zero. 



I . PRM 



Driver access: 

Not initialized, read-only. 

Description: 

Device-dependent parameters constructed from the last 6 words 
of the DPB. Note that if the I/O function is a transfer 
(refer to the description of D.MSK in Section 4.1.2.1), the 
buffer address (first DPB device-dependent parameter) is 
translated to an equivalent address doubleword. Therefore, 
device-dependent parameter n is copied to I. PRM +(2*n)+2. 
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4.1.1.2 The QIO Directive Parameter Block (DPB) - The QIC DPB is 
constructed as shown in Figure 4-2. 

The parameters in the DPB have the following meanings. 
Length (required) : 

The length of the DPB, which for the RSX-llM QIO directive is 
always fixed at 12 words. 

Die (required) : 

Directive Identification Code. For the QIO directive, this value 
is 1. For QIOW it is 3. 

Function Code (required) : 

The code of the requested I/O function (0 through 31.). 



Length 


Die 


Function code 


Modifier 


Reserved 


LUN 


Priority 


EFN 


I/O status block address 


AST address 






Device- 
ripppndent 


parameters 







4 

6 

10 

12 

14 






Figure 4-2 QIO Directive Parameter Block (DPB) 

Modifier : 

Device-dependent modifier bits. 
Reserved; 

Reserved byte; must not be used. 
LUN (required) : 

Logical Unit Number. 
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Priority; 



Request priority. Ignored by RSX-llM, but space must be 
allocated for RSX-llD compatibility. 

EFN (optional) : 

Event flag number. Zero indicates no event flag. 

I/O Status Block Address (optional) : 

This word contains a pointer to the I/O status block, which is a 
2-word, device-dependent I/O-completion data packet formatted as: 

Byte 

I/O status byte. 
Byte 1 

Augmented data supplied by the driver. 

Bytes 2 and 3 

The contents of these bytes depend on the value of byte 0. 
If byte 0=1, then these bytes usually contain the 
processed byte count. If byte does not equal 0, then the 
contents are device-dependent. 

AST Address (optional): 

Address of an AST service routine. 

Device Dependent Parameters: 

Up to six parameters specific to the device and I/O function to 
be performed. Typically, for data transfer functions, the 
following four are used: 

Buffer address 

Byte count 

Carriage control type 

Logical block number 

The fields for any optional parameters not specified must be filled 
with zeros. 



4.1.2 The Device Control Block (DCB) 

Figure 4-3 is a schematic layout of the DCB. The DCB describes the 
static characteristics of a device controller and the units attached 
to the controller. All fields must be specified except D.PCB, which 
is required only if the loadable-driver option has been selected. 
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4.1.2.1 DCB Details - The fields in the DCB are described below: 
D.LNK (link to next DCB)* 
Driver access: 

Initialized, not referenced. 



f^^% 



Description: 

Address link to the next DCB. A zero in this field indicates 
the last (or only) DCB in the chain. 

D.UCB (pointer to first UCB) 

Driver access: 

Initialized, not referenced. 



D.LNK 


Link to next DCB (0=last) 





D.UCB 


Link to first UCB 


2 


D.NAM 


Generic device n.3me 


4 


D.UNIT 


Highest unit no. 


Lowest unit no. 


6 


D.UCBL 


Length of UCB 


10 


D.DSP 


Address of driver dispatch table 


12 


D.MSK 


Legal function mask bits 0-15. 


14 




Control function mask bits 0-15. 


16 




No-op'ed function mask bits 0-15. 


20 




ACP function mask bits - 15. 


22 




Legal function mask bits 16.-31. 


24 




Control function mask bits 16.-31. 


26 




No-op'ed function mask bits 16.-31. 


30 




ACP function mask bits 1 6. - 3 1 . 


32 


D.PCB 


Address of partition control block 
1 J 


34 
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Figure 4-3 Device Control Block 



* Parenthesized contents indicate value to be initialized in the data 
base source code. 
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Description: 

Address link to the U.DCB field of the first, and possibly 
the only, UCB associated with the DCB. For a given DCS, all 
UCBs are in contiguous memory locations and must all have the 
same length. 

D.NAM (ASCII device name) 

Driver access? 

Initialized, not referenced. 

Description: 

Generic device name in ASCII by which device units are 
mnemonically referenced. 

D.UNIT (unit number range) 

Driver access: 

Initialized, not referenced. 

Description: 

Unit number range for the device. This range covers those 
logical units available to the user for device assignment. 
Typically, the lowest number is zero, and the highest is n-1, 
where n is the number of device-units described by the DCB. 

D.UCBL (UCB length) 

Driver access: 

Initialized, not referenced. 

Description: 

The UCB can have any length to meet the needs of the driver 
for variable storage. However, all UCB's for a given DCB 
must have the same length. The specified length must include 
prefix words (U.LUIC and U.OWN) if present. 

D.DSP (dispatch table pointer) 

Driver access: 

Initialized, not referenced. 

Description: 

Address of the driver dispatch table. 

When the Executive wishes to enter the driver at any of the 
four entry points contained in the driver dispatch table, it 
accesses D.DSP, locates the appropriate address in the table, 
and calls the driver at that address. A zero table address 
indicates that the (loadable) driver is not in memory. For a 
loadable driver, then, this field must be initialized to 
zero. If the driver does not process a given function, then 
it simply supplies the address of a return. 
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You must provide a driver dispatch table in the driver 

source. The label on this table is of the form $xxTBL; it 

must be a global label. The designation xx is the itl9h 

2-character generic device name for the device. Thus, $TTTBL T^ 

is the global label on the driver dispatch table for the 

generic device name TT. This table is an ordered, 4-word 

table containing the following entry points: 

I/O Initiator 

Cancel I/O 

Device Timeout 

Power failure 

When a driver is entered at one of these entry points, entry 
conditions are as follows: 

At Initiator: 

If UC.QUE=1 - ^ 

R5 = UCB address "^^ 

R4 = see address 
Rl = Address of the I/O Packet 

If UC.QUE=0 

R5 = UCB address 

Interrupts are allowed. (UC.QUE is a bit in U.CTL in the 
UCB. See Section 4.1.4.1.) 

At Cancel I/O: 

R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

Rl = Address of TCB of current task 

RO = Address of active I/O packet 

Device interrupts at or below the priority of the 
requesting device are locked out. 

At Device Timeout: 

R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

R2 = Address of device CSR 

RO = I/O status code lE.DNR (Device Not Ready) 

Device interrupts at or below the priority of the 
requesting device are locked out. 

At Power Failure: 

R5 = UCB address 
R4 = SCB address 
R3 = Controller index 

Interrupts are allowed. The power failure entry point of 
a loadable driver is called by LOAd only for units that 
are online and have UC.PWF set. 
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D.MSK (function masks) 

Driver aiccess: 

Initialized, not referenced. 

Description: 

There are 8 words, beginning at D.MSK, that are critical to 
the proper functioning of a device driver. The Executive 
uses these words to validate and dispatch the I/O reauest 
specified by a QIO directive. The following description 
applies only to non-file-structured devices.* Four masks, 
with 2 words per mask, are described by the bit 
configurations that you establish for these words: 

1. Legal function mask 

2. Control function mask 

3. No-op'ed function mask 

4. ACP function mask 

The QIO directive allows for 32 possible I/O functions. The 
masks, as stated, are filters to determine validity and I/O 
requirements for the subject driver. 



The Executive fi 
through the fo 
high-order byte 
directive. The 
byte is eguivale 
you want the 
you must set the 
numerically cor 
the code for 
representation 
mask, you must s 



Iters the function code in the I/O request 
ur masks. The I/O function code is the 
of the function parameter issued with the 010 
decimal representation of that high-order 
nt to the decimal bit number of the mask. If 
function to be true in one of the four masks, 
bit in that mask in the position that 
responds to the function code. For example, 
lO.RVB is 21 (octal) and its decimal 
is 17. If you want lO.RVB to be true for a 
et bit number 17 in the mask. 



The masks are laid out in memory in two 4-word groups. Each 
4-word group covers 16 function codes. The first 4 words 
cover the function codes 0-15; the second 4 words cover 
codes 16-31. Below is the exact layout used for the driver 
example in Section 6.2.2. 

; LEGAL FUNCTION MASK CODES 0-15. 
; CONTROL FUNCTION MASK CODES 0-15. 
;NO-OP'ED FUNCTION MASK CODES 0-15. 
;ACP FUNCTION MASK CODES 0-15. 
; LEGAL FUNCTION MASK CODES 16.-31. 
; CONTROL FUNCTION MASK CODES 16.-31. 
;NO-OP'ED FUNCTION MASK CODES 16.-31. 
;ACP FUNCTION MASK CODES 16.-31. 



* Although no DIGITAL publication describes writing drivers for 
file-structured devices (drivers that interface with FllACP) , many 
users have successfully written a disk/drum driver by using a 
DIGITAL-supplied driver as a template. For example, the RFll driver 
(DFDRV) could be modified to be a drum driver. 



.WORD 


140033 


.WORD 


30 


.WORD 


140000 


.WORD 





.WORD 


5 


.WORD 





.WORD 


1 


.WORD 


4 
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The mask words filter sequentially as follows: 
Legal Function Mask: 

Legal function values have the corresponding bit position in 
this word set to 1. Function codes that are not legal are 
rejected by QIC directive processing, which returns lE.IFC in 
the I/O status block, provided an lOSB address was specified. 

Control Function Mask: 

If any device-dependent data exists in the DPB, and this data 
does not require further checking by the 010 directive 
processor, the function is considered to be a control 
function. Such a function allows QIO directive processing to 
copy the DPB device-dependent data directly into the I/O 
Packet. 

No-op'ed Function Mask: 

A no-op function is any function that is considered 
successful as soon as it is issued. If the function is a 
no-op, QIO directive processing immediately marks the request 
successful; no additional filtering occurs. 

ACP Function Mask: 

If a function code is legal, but specifies neither a control 
function nor a no-op, then it specifies either an ACP 
function or a transfer function. If a function code requires 
intervention of an Ancillary Control Processor (ACP) , the 
corresponding bit in the ACP function mask must be set. ACP 
function codes must have a value greater than 7. 

In the specific case of read-write virtual functions, the 
corresponding mask bits may be set at your option. If the 
corresponding mask bits for a read-write virtual function are 
set, QIO directive processing recognizes that a file-oriented 
function is being requested to a non-file-structured device 
and converts the request to a read-write logical function. 

This conversion is particularly useful. Consider a 
read-write virtual function to a specific device: 

1. If the device is file-structured and a file is open 
on the specified LUN, the block number specified is 
converted from a virtual block number in the file to 
a logical block number on the medium, and the request 
is queued to the driver as a read-write logical 
function. 

2. If the device is file-structured and no file is open 
on the specified LUN, then an error is returned and 
no further action is taken. 

3. If the device is not file-structured, then the 
request is simply transformed to a read-write logical 
function and is queued to the driver. (Specified 
block number is unchanged.) 



JttUtk 
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Transfer Function Processing: 

Finally, if the function is not an AGP function, then, by 
default, it is a transfer function. All transfer functions 
cause the QIC directive processor to check the specified 
bufifer for legality (that is, inclusion within the address 
space of the requesting task) and proper alignment (word or 
byte). In addition, the processor checks the number of bytes 
being transferred for proper modulus (that is, nonzero and a 
proper multiple) . 
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Creating Mask Words: 

Creating function mask words involves five steps; 

1. Establish the I/O functions available on the device 
for which driver support is to be provided. 

2. Build the Legal Function mask: Check the standard 
RSX-llM function mask values in Table 4-1 for 
equivalencies. Only the lO.KIL function is 
mandatory. 10. ATT and lO.DET functions, if used, 
must have the RSX-llM system interpretation. Digital 
suggests that functions having an RSX-llM system 
counterpart use the RSX-llM code, but this is 
required only when the device is to be used in 
conjunction with an ACP. From the supported function 
list in Table 4-1, you can build the two Legal 
Function mask words. 

3. Build the Control Function mask by asking: 

Does this function carry a standard buffer address 
and byte count in the first two device-dependent 
parameter words? 

If it does not, then either it qualifies as a control 
function, or the driver itself must effect the 
checking and conversion of any addresses to the 
format required by the driver. See Section 6.3 for 
an example of a driver that does this. (Buffer 
addresses in standard format are automatically 
converted to Address Doubleword format.) 

Control functions are essentially those functions 
whose DPBs do not contain buffer addresses or counts. 

4. Create the No-op Function mask by deciding which 
legal functions are to be no-op'ed. Typically, for 
compatibility with Pile Control Services (PCS) or 
Record Management Services (RMS) on 
non-file-structured devices, the file access/deaccess 
functions are selected as legal functions, even 
though no specific action is required to access or 
deaccess a non-file-structured device; thus, the 
access/deaccess functions are no-op'ed. 

5. Finally, include the ACP functions Write Virtual 
Block and Read Virtual Block for those drivers that 
support both read and write. (Include only one 
related ACP function if the driver supports only read 
or write.) Other ACP functions that might be included 
fall into the non-conventional driver classification 
and are beyond the scope of this document. 

D.PCB (Partition Control Block) 

Driver access; 

Initialized, not referenced. 

Description: 

Address of the driver's Partition Control Block (PCB) . This 
word is present in the DCB if and only if the loadable-driver 
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SYSGEN option has been selected. It must be initialized to 
zero. The DCB can be extended by adding words after D.PCB. 

A PCB exists for every partition in a system. MCR creates a 
PCB when the SET /MAIN or SET /SUB commands are given. If a 
driver is loadable, its PCB describes the partition in which 
it resides. 

The Executive uses D.PCB together with D.DSP (the address of 
the driver dispatch table) to determine whether a driver is 
loadable or resident, and, if loadable, whether or not it is 
in memory. Zero and nonzero values for these two pointers 
have the following meanings: 



.D.DSP; 



D.PCB: 



= 



=^0 



= 


¥0 


Loadable 
driver, 
not in 
memory 


Resident 
driver 


(not 
possible) 


Loadable 
driver, 

in memory 
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4.1.2.2 Establishing I/O Fanction Masks - Table 4-1 is supplied to 
assist you in determining the proper values to set in the function 
masks. The mask values are given for each I/O function used by 
DIGITAL-supplied drivers. The bit number allows you to determine 
which mask group to use: for bits numbered through 15, use the mask 
value for a word in the first 4-word group; for bits numbered 16 
through 31, use the mask value for a word in the second 4-word group. 



Table 4-1 
Mask Values for Standard I/O Functions 



Bit 


Mask 


Related 


I/O 




# 


Value 


Symbolic 


Function 







1 


lO.KIL 


Cancel I/O 




1 


2 


lO.WLB 


Write Logical Block 




2 


4 


lO.RLB 


Read Logical Block 




3 


10 


10. ATT 


Attach Device 




4 


20 


lO.DET 


Detach Device 




5 


40 




General Device Control 




6 


100 




General Device Control 




7 


200 




General Device Control 




8 


400 




Diagnostics 




9 


1000 


lO.FNA 


Find File in Directory 




10 


2000 


lO.ULK 


Unlock Block 




11 


4000 


10 . RNA 


Remove Pile from Directory 




12 


10000 


lO.ENA 


Enter File in Directory 




13 


20000 


lO.ACR 


Access File for Read 




14 


40000 


lO.ACW 


Access File for Read/Write 




15 


100000 


10. ACE 


Access File for Read/Write/Ex 


tend 



(continued on next page) 
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Table 4-1 (Cont.) 
Mask Values for Standard I/O Functions 



Bit 
# 



16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 



Mask 
Value 



1 

2 

4 

10 

20 

40 

100 

200 

400 

1000 

2000 

4000 

10000 

20000 

40000 

100000 



Related 
Symbolic 



lO.DAC 
lO.RVB 
lO.WVB 
10. EXT 
10. ORE 
10. DEL 
10. RAT 
10. WAT 
lO.APC 



I/O 
Function 



Deaccess File 

Read Virtual Block 

Write Virtual Block 

Extend File 

Create File 

Mark File for Delete 

Read File Attributes 

Write File Attributes 

ACP Control 

Unused 

Unused 

Unused 

Unused 

Unused 

Unused 

Unused 



Of the function mask values listed 
mandatory and has a fixed inte 
lO.DET are used, they must have the 
RSX-llM/M-PLUS I/O Drivers Refer 
standard I/O functions.) If QIO d 
function code of 3 or 4 and the cod 
these codes represent Attach Device 
The other codes are suggested 
establish all other function-cod 
devices. The mask words must refle 



in Table 4-1, only 
rpretation. However, if 

standard meaning. (Ref 
ence Manual for a des 
irective processing en 
e is not no-op 'ed, 010 a 

and Detach Device, re 
but not mandatory. You 
e values on non-file 
ct the proper filtering 



lO.KIL is 
10. ATT and 
er to the 
cription of 
counters a 
ssurties that 
spectively. 
are free to 
-structured 
process. 



file-structured device, the 



If a driver is being written for a ^ ^-^ ■ v. a 

standard function mask values of Table 4-1 must be established. 



4.1.3 The Status Control Block (SCB) 

Figure 4-4 is a layout of the SCB. The SCB describes the status of 
control unit that can run in parallel with all other control units. 
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S.LHD 



S.PRI 

S.VCT 

S.CTM 

S.ITM 

S.CON 

S.STS 

S.CSR 
S.PKT 
S.FRK 



S.MPR 



Device I/O queue 
listhead 



Vector addre5s44 



Device priority 



Timeout count: 



Initial 



Controller status 



Current 



Controller index 



Address of control status register 



Address of current l/C packet 



Fork link word 



Fork PC 



Fork R5 



Fork R4 



Relocation base of driver's partition 



Storage required for 
NPR UN I BUS devices 
with 22-bit addressing 




2 

4 
6 
10 
12 
14 
16 
20 
22 
24 
26 
30 



j(BB^^Ik 



Figure 4-4 Status Control Block 

4.1.3.1 SCB Details - The fields in the SCB are described below: 
S.LHD (first word equals zero; second word points to first)* 

Driver access: 

Initialized, not referenced. 

Description: 

Two words forming the I/O queue listhead. The first word 
points to the first I/O Packet in the queue, and the second 
word points to the last I/O Packet in the queue. If the 
queue is empty, the first word is zero, and the second word 
points to the first word. 



* Parenthesized contents indicate values to be initialized in the 
data base source code. 
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S.PRI (device priority) 

Driver access: 

Initialized, read-only. 

Description: 

Contains the priority at which the device interrupts. Use 
symbolic values (for example, PR4) to initialize this field 
in your data base source. These symbolic values are defined 
by issuing the HWDDF$ macro (refer to the sample data base in 
Section 6.2.1 and the listing of the HWDDF$ macro in Appendix 
C) . 

S.VCT (interrupt vector divided by four) 

Driver access: 

Initialized, not referenced. 

Description: 

Interrupt vector address divided by four. For loadable 
drivers, the MCR/VMR LOA[D] function uses this field and the 
existence of driver symbol (s) $xxINT, $xxINP, and $xxOUT to 
initialize the device interrupt vector. 

S.CTM (initialize to zero) 

Driver access: 

Not initialized, read-write. 

Description: 

RSX-llM supports device timeout, which enables a driver to 
limit the time that elapses between the issuing of an I/O 
operation and its termination. The current timeout count (in 
seconds) is initialized by moving S.ITM (initial timeout 
count) into S.CTM. The Executive clock service (in module 
TDSCH) examines active times, decrements them, and, if they 
reach 0, calls the driver at its device timeout entry point. 

The internal clock count is kept in 1-second increments. 
Thus, a time count of 1 is not precise because the internal 
clocking mechanism is operating asynchronously with driver 
execution. The minimum meaningful clock interval is 2 if you 
intend to treat timeout as a consistently detectable error 
condition. Note, if the count is 0, that no timeout occurs; 
a zero value is, in fact, an indication that timeout is not 
operative. The maximum count is 255. You are responsible 
for setting this field. Resetting occurs at actual timeout 
or within $FORK. 

S.ITM (set to initial timeout count) 

Driver access: 

Initialized, read-only. 
Description: 

Contains the initial timeout value. 
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S.CON (controller number times 2) 

Driver access: 

Initialized, read-only. 

Description: 

Controller number multiplied by 2. This field is used by 
drivers that are written to support more than one controller. 
A driver may use S.CON to index into a controller table 
created and maintained internally by the driver itself. By 
indexing the controller table, the driver can service the 
correct controller when a device interrupts. See Section 4.2 
for an example. 

S.STS (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

Establishes the controller as busy/not busy (nonzero/zero) . 
This byte is the interlock mechanism for marking a driver as 
busy for a specific controller. The byte is tested and set 
by ?GTPKT and reset by $IODON. 

S.CSR (Control Status Register address) 

Driver access: 

Initialized, read-only. 

Description: 

Contains the address of the Control Status Register (CSR) for 
the device controller. The driver uses S.CSR to initiate I/O 
operations and to access, by indexing, other registers 
related to the device that are located in the I/O page. This 
address need not be a CSR; it need only be a member of the 
device's register set. It is accessed at system bootstrap 
time to determine if the interface exists on the system 
hosting the Executive. The Executive uses S.CSR to set the 
offline bit at bootstrap so that system software can be 
interchanged between systems without an intervening system 
generation. The MCR LOAD function also references S.CSR when 
it processes a loadable data base. Otherwise, only the 
driver itself accesses S.CSR,, 

S.PKT (reserve 1 word of storage) 

Driver access: 

Not initialized, read-only. 

Description: 

Address of the current I/O Packet established by $GTPKT. The 
Executive uses this field to retrieve the I/O Packet address 
upon the completion of an I/O request. S.PKT is not zeroed 
after the packet is completed. 
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S.FRK (reserve 4 or 5 words of storage) 
Driver access;; 

Not initialized, not referenced. 
Description: 

The 4 words starting at S.FRK are used for fork-block storage 
if and when the driver deems it necessary to establish itself 
as a Fork process. Fork-block storage preserves the state of 
the driver, which is restored when the driver regains control 
at fork level. This area is automatically used if the driver 
calls $FORK. 

The fork block is 5 words long instead of 4 if two conditions 
ace met: 

1. Loadable drivers have been selected as a SYSGEN 
option; and 

2. The system is mapped. 

If these conditions are met, and the fork block is 5 words 
long, you must not use the fork block for any other purpose. 
In other words, you may not share the space reserved for the 
fork block; if you attempt to do so, you will destroy the 
loadable driver's relocation base. In addition, the 5-word 
fork block should always be part of the SOB if the two above 
conditions are met. 

S.MPR (reserve 6 words of storage) 

Driver access: 

Initialised, read-only. 

Description: 

Drivers use the 6 words starting at S.MPR fo^ .^"^o^TP^o^^^^?^ 
request (NPR) devices attached to a PDP-11/70 with 22-bit 
addressing. See Appendix B for details on initializing 
S.MPR. 



4.1.4 The Unit Control Block (UCB) 

Figure 4-5 is a layout of the UCB (a variable-length control block). 
One UCB exists for each physical device-unit generated into a system 
configuration. For user-added drivers, this control block is defined 
as part of the source code for the driver data structure. 



4.1.4.1 UCB Details - The fields in the UCB are described below: 
U.LUIC 

Driver access: 

Not initialized, not referenced. 
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Description: 

For terminal UCB ' s only, and only in multiuser systems; 
logon UIC of the user at the particular terminal. 



the 



U.LUIC 


r 

Log-on UIC 


"1 
1 


-4 


U.OWN 


Owning terminal UCB address 


-2 


U.DCB 


Back pointer to DCB 





U.RED 


Redirect UCB pointer 


2 


U.CTL \ 
U.STS f 


Unit status 


Control flags 


4 


U.UNIT ) 
U.ST2 j 


Unit status 


Physical unit no. 


6 


U.CW1 


Characteristics word 1 


10 


U.CW2 


Characteristics word 2 


12 


U.CW3 


Characteristics word 3 


14 


U.CW4 


Characteristics word 4 


16 


U.SCB 


Pointer to SCB 


20 


U.ATT 


TCB address of attached task 


22 


U.BUF 


Buffer relocation bias 


24 


U.BUF+2 


Buffer address 


26 


U.CNT 


Byte count 


30 




Device- 


32 




dependent 








storage 



Figure 4-5 Unit Control Block 

U.OWN (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

Only in multiuser systems: the UCB address of the owning 
terminal for allocated devices. 
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U.DCB (pointer to associated DCB) 

Driver access: 

Initialized, not referenced. 

Description: 

Backpointer to the corresponding DCB. Because the UCB is a 
key control block in the I/O data structure, access to other 
control blocks usually occurs by means of links implanted in 
the UCB. 

U.RED (redirect pointer — initialized to point to U.DCB of the UCB) 

Driver access: 

Initialized, not referenced. 

Description: 

Contains a pointer to the UCB to which this device-unit has 
been redirected. This field is updated as the result of an 
MCR Redirect command. The redirect chain ends when this word 
points to the beginning of the UCB itself (U.DCB of the UCB 
to be precise) . 

U.CTL (set by you) 

Driver access; 

Initialized, not referenced. 

Description: 

U.CTL and the function mask words in the DCB drive 010 
directive processing. You are responsible for setting up 
this bit pattern. Any inaccuracy in the bit setting of U.CTL 
produces erroneous I/O processing. Bit symbols and their 
meanings are as follows: 

UC.ALG - Alignment bit. 

If this bit = 0, then byte alignment of data buffers is 
allowed. If UC.ALG = 1, then buffers must be 
word-aligned. 

UC.ATT - Attach/Detach notification. 

If this bit is set, then the driver is called when $GTPKT 
processes an Attach/Detach I/O function. Typically, the 
driver does not need to obtain control for Attach/Detach 
requests, and the Executive performs the entire function 
without any assistance from the driver. 

UC.KIL - Unconditional Cancel I/O call bit. 

If set, the driver is called on a Cancel I/O request, 
even if the unit specified is not busy. Typically, the 
driver is called on Cancel I/O only if an I/O operation 
is in progress. 
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UC.QUE - Queue bypass bit. 

If set, the QIC directive processor calls the driver *^f^ 
prior to queuing the I/O packet. After the processor 
makes this call, the driver is responsible for the 
disposition of the I/O packet. Typically, the processor 
queues an I/O Packet prior to calling the driver, which 
later retrieves it by a call to $GTPKT. 

UC.PWF - Unconditional call on power failure bit. 

If set and the unit is online, the driver is always to be 
called when the system is bootstrapped or power is 
restored after a power failure occurs. Typically, the 
driver is called on power restoration only when an I/O 
operation is in progress. Additionally, for loadable 
drivers, the driver is called when LOAded if the unit is 
online and UC.PV?F is set. 

UC.NPR - NPR device bit. 

If set, the device is an NPR device. This bit determines .i^^ 
the format of the 2-word address in U.BUF (details given 
in the discussion of U.BUF below) . 

UC.LGH - Buffer size mask bits (2 bits). 

These two bits are used to check whether the byte count 
specified in an I/O request is a legal buffer modulus. 
You select one of the values below by ORing into the byte 
a 0, 1, 2, or 3„ 

00 - Any buffer modulus valid J^fej 

01 - Must have vi^ord alignment modulus 

10 - Combination invalid 

11 - Must have double word-alignment modulus 

UC.ALG and UC.LGH are independent settings. 

UC.ATT, UC.KIL, UC.QUE, and UC.PWF are usually zero, 

especially for conventional drivers. Every driver, however, 

must be concerned with its particular values for UC.ALG, 

UC.NPR, and UC.LGH. You are totally responsible for the 

values in these bits, and erroneous values are likely to ^|^ 

produce unpredictable results. 

U.STS (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

This byte contains device-independent status information. 
The bit meanings are as follows: 

US.BSY - If set, device-unit is busy. 

US.MNT - If set, volume is not mounted. 

US. FOR - If set, volume is foreign. 

US.MDM - If set, device is marked for dismount. """^l 
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The unused bits in U.STS are reserved for system use and 
expansion, US.MDM, US.MNT, and US. FOR apply only to 
mountable devices. 

U.UNIT (unit number) 

Driver access: 

Initialized, read-only. 

Description: 

This byte contains the physical unit number of the 
device-unit. If the controller for the device supports only 
a single unit, the unit number is always zero. 

U.ST2 (set by you) 

Driver access: 

Initialized, not referenced. 

Description: 

This byte contains additional device-independent status 
information. The bit meanings are as follows: 

US.OFL - If set, the device is offline (that is, not in 
the configuration) . 

US. RED - If set, the device cannot be redirected. 

US. PUB - If set, the device is a public device. 

US.UMD - If set, the device is attached for diagnostics. 

The remaining bits are reserved for system use and expansion. 

U.CWl (set by you) 

Driver access: 

Initialized, not referenced. 

Description: 

The first of a 4-word contiguous cluster of device 
characteristics information. U.CWl and U.CW4 are 
device-independent. U.CW2 and U.CW3 are device-dependent. 
The four characteristics words are retrieved from the UCB and 
placed in the requester's buffer on issuance of a Get LUN 
information (GLUN$) Executive directive. It is your 
responsibility to supply the contents of these four words in 
the assembly source code of the driver's data structure. 

U.Cva is defined as follows. (If a bit is set to 1, the 
corresponding characteristic is true for the device.) 
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DV.REC Bit — Record-oriented device 

DV.CCL Bit 1 — Carriage-control device 

DV.TTY Bit 2 — Terminal device 

DV.DIR Bit 3 — Directory device 

DV.SDI Bit 4 — Single directory device 

DV.^SQD Bit 5 — Sequential device 

DV.UMD Bit 7 — Device supports user-mode diagnostics 

DV.MBC Bit 8 — Device attached to a 22-bit MASSBUS 

controller 

DV.SWL Bit 9 — Unit is software write-locked 

DV.PSE Bit 12 — Pseudo device 

DV.COM Bit 13 — Device mountable as a communications channel 

DV.Fll Bit 14 — Device mountable as a FILES-11 device 

DV.MNT Bit 15 — Device mountable 

U.CW2 (initialize to zero) 

Driver access: 

Initialized, read-write. 

Description: 

Specific to a given device driver (available for working 
storage or constants).* 

U.CW3 (initialize to zero) 

Driver access: 

Initialized, read-write. 

Description: jUll^ 

Specific to a given device driver (available for working 
storage or constants).* 

U.CW4 (set by you) 

Driver access: 

Initialized, read-only. 

Description: 

Default buffer size. This word is changed by the MCR command 
SET /BUF=. 

U.SCB (SCB pointer) 

Driver access: 

Initialized, read-only. 



* Exception: for block-structured devices, U.CW2 and U.CW3 may not 
be used for working storage. In drivers for block-structured devices 
(disks and DECtape) , these two words must be initialized to a 
double-precision number giving the total number of blocks on the 
device. Place the high-order bits in the low-order byte of U.CW2 and 
the low-order bits in U.CW3. 

4-24 May 1979 



WRITING AN I/O DRIVER — PROGRAMMING SPECIFICS 

Description: 

This field contains a pointer to the SCB for this UCB. In 
general, R4 contains the value in this word when the driver 
is entered by way of the driver dispatch table, because 
service routines frequently reference the SCB. 

U.ATT (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

If a task has attached itself to the device-unit, this field 
contains its TCB address. 

U.BUF (reserve 2 words of storage) 

Driver access: 

Not initialized, read-write. 

Description: 

U.BUF labels 2 consecutive words that serve as a 
communication region between $GTPKT and the driver. If a 
non-transfer function is indicated (in D.MSK) , then U.BUF, 
U.BUF+2, and U.CNT receive the first 3 parameter words from 
the I/O Packet. 

For transfer operations, the format of these 2 words depends 
on the setting of UC.NPR in U.CTL. The driver does not 
format the words; all formatting is completed before the 
driver receives control. For unmapped systems, the first 
word is zero, and the second word is the physical address of 
the buffer. For mapped systems, the format is determined by 
the UC.NPR bit, which is set for an NPR device and reset for 
a program-transfer device. 

The format for program-transfer devices is identical to that 
for the second 2 words of I . lOSB in the I/O Packet. See 
Section 4.1.1.1. 

In general, the driver does not manipulate these words when 
performing I/O to a program-transfer device. Instead, it 
uses the Executive routines Get Byte, Get Word, Put Byte, and 
Put Word to effect data transfers between the device and the 
user's buffer. 

For NPR device drivers, the word layout is as follows: 
Word 1 

Bit Go bit initially set to zero 

Bits 1-3 Function code — set to zeros 

Bits 4,5 Memory extension bits 

Bits 6 Interrupt enable — set to zero 

Bits 7-15 Zero 

Word 2 

Bits 0-15 Low-order 16-bits of physical address 
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It is your responsibility to set the function code, interrupt 
enable, and go bits. This action must be accomplished by a 
Bit Set (BIS) operation so that the extension bits are not 
disturbed. The driver must move these words into the device 
control registers to initiate the I/O operation. 

Note that when the system is unmapped, bits 4 and 5 are 
always zero, but this fact is transparent to the driver. 
Thus, NPR device drivers are not cognizant of the mapping 
state in the system. 

The construction of U.BUF, U.BUF+2, and U.CNT occurs only if 
the requested function is a transfer function; if it is not, 
these 3 words contain the first 3 words of the I/O Packet. 

The details of the construction of the Address Doubleword 
appear in Appendix A, 

U.CNT (reserve 1 word of storage) 

Driver access: 

Not initialized, read-write. 

Description: 

Contains the byte count of the buffer described by U.BUF. 
The driver uses this field in constructing the actual device 
request. 

U.BUF and U.CNT keep track of the current data item in the 
buffer for the current transfer (except for NPR transfers) . 
Because this field is being altered dynamically, the I/O 
Packet may be needed to reissue an I/O operation, for 
instance after a powerfail or error retry. 

Device-Dependent Words: 

Driver access: 

Not initialized, read-write. 

Description: 

You establish this variable-length block of words to suit 
device-specific requirements. 



4.1.5 The Device Interrupt Vector 

For resident drivers only, the device interrupt vector must be 
initialized when defining data structures, and not dynamically. This 
practice makes the driver code independent of device register address 
assignments and of the actual location of the interrupt vector. The 
driver data structure must include a storage assignment and 
initialization for the interrupt vector with the priority set to PR7 . 
See lines 81 thru 85 in Section 6.2.1 (Section 6.2.1 contains the 
source code for the data structure of a sample resident driver) . 

Writers of loadable drivers do not initialize the device interrupt 
vector. The vector is dynamically established by LOA[D] when the 
driver is loaded. When a driver is unloaded, UNLoad sets the vector 
to the system nonsense interrupt entry point. 
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4.2 MULTICONTROLLER DRIVERS 

This section discusses the conditional code needed at the interrupt 
entry point of a driver that may handle one or several device 
controllers. This discussion leads to a description in the next 
section of the system macro INTSV$ . INTSV$ contains multicontroller 
conditionals and other features to simplify interrupt-entry coding. 

Figure 4-6 shows the interrupt-entry coding from the paper-tape-punch 
driver. This is an earlier version of the driver presented m its 
entirety in Section 6.2.2. 

The coding is conditionalized on P$$Pll-l. The symbol P$$P11 
represents the number of controllers and is set at SYSGEN. 

In a multicontroller device configuration, the controllers are 
numbered starting with 0. The code for a multicontroller driver 
contains a table (called CNTBL in the example in Figure 4-6) whose 
length in words is equal to the number of controllers. A number 
called the controller index— equal to the controller number times 
2 — is stored in the SCB for each controller, in byte S.CON. 

When an I/O request occurs, and the driver is called at its initiator 
entry point, the driver first calls $GTPKT to obtain an I/O packet to 
process. Among the values returned by $GTPKT are the controller index 
(obtained from S.CON in the SCB) and the address of the UCB for the 
unit requesting I/O service. 

The driver stores the requesting unit's UCB address in the controller 
table (CNTBL) at an offset equal to the controller index. Thus, for 
the driver at its interrupt entry point to access the requesting UCB, 
it needs simply to obtain the controller index. 

The controller index is obtained from the controller number, which is 
encoded in the lowest 4 bits of the PS word in the device's interrupt 
vector. At its interrupt entry point the driver first saves the PS 
(line 9 in Figure 4-6), which was set from the device's interrupt 
vector upon interrupt. The PS must be saved with the ^^^f^ 
instruction of interrupt code because its lower 4 bits are the 
processor condition code bits, which generally change after each 
instruction is issued. Later, after the call to $INTSV, the driver 
constructs the controller index from the saved PS (lines 17-19). It 
then uses this index to obtain the UCB address (line 20) . 

For single-controller devices, CNTBL is 1 word, TEMP is not needed to 
store the PS, and the UCB address is always the first (and only) entry 
in CNTBL. 
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1 ; + 

2 ; **-$PPINT-PCll PAPER TAPE PUNCH CONTROLLER INTERRUPTS 

3 ;- 
4 

" ;; ;REF LABEL 



;;;SAVE CONTROLLER NUMBER 



5 $PPINT:: 




6 






7 


.IF GT 


P$$P11-1 


8 






9 


MOV 


PS, TEMP 


10 






11 


.IFTF 




12 






13 


CALL 


$INTSV,PR4 


14 






15 


.IFT 




16 






17 


MOV 


TEMP,R4 


18 


BIC 


#177760, R4 


19 


ASL 


R4 


20 


MOV 


CNTBL(R4) ,R5 


21 






22 


.IFF 




23 






24 


MOV 


CNTBL,R5 


25 






26 


.ENDC 





;;;SAVE REGISTERS AND SET PRIORITY 



; RETRIEVE CONTROLLER NUMBER 
; CLEAR ALL BUT CONTROLLER NUMBER 
/•CONVERT TO CONTROLLER INDEX 
; RETRIEVE ADDRESS OP UCB 



;;; RETRIEVE ADDRESS OF UCB 



m^, 



Figure 4-6 Conditional Code for a Multicontroller Driver 



4.3 THE INTSV$ MACRO 

INTSV$ is a system macro that minimizes coding differences between 
loadable and resident drivers. INTSV$ contains conditionally 
assembled code to handle: 

1. Single or multiple controllers 

2. Loadable or resident drivers 

3. Mapped or unmapped systems 

All the code in Figure 4-6 between lines 7 and 26 may be replaced by 
the INTSV$ macro (as is done in the sample driver illustrated in 
Section 6.2.2). This is required for loadable drivers on mapped 
systems, because interrupts from hardware devices must be processed in 
kernel address space. In particular, the decoding of the PS word and 
the call to $INTSV must be done before entering the driver. Thus, a 
call to the Executive routine $INTSV within a loadable driver is 
illegal, and the MCR LOA[D] function returns an error if loading is 
attempted. 

When the INTSV$ macro is used for a loadable driver in a mapped 
system, the code from lines 9 to 19 inclusive (Figure 4-6) is not 
assembled as part of the driver. Instead, the LOA[D] function 
allocates a block of dynamic memory in kernel address space to contain 
the interrupt coding. This block, called the Interrupt Control Block 
(ICB) , also contains coding to: 
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1. Save th€i kernel mapping (APRS) 

2. Load APR5 to map the driver 

3. Transfer to the driver 

4. Restore the mapping after return 

The LOA[D] function also sets up the controller's interrupt vector so 
that hardware interrupts point to the ICB. 

Finally, the use of the INTSV$ macro in a loadable driver on a mapped 
system requires that the symbol LD$xx (where xx is the 2-character 
device mnemonic) be defined either in the driver source or the 
assembly prefix file RSXMC.MAC. 



4.3.1 Format 

The format of the INTSV$ macro is: 

INTSV$ xx,pri,nctlr [ ,pssave ,ucbsave] 
where: 

XX is the 2-character device mnemonic. 

pri is the priority of the device (the priority that would 
be used in a call to $INTSV) . 

nctlr is the number of controllers the driver services. 

pssave is an optional argument specifying a variable in which 
to save the PS word. If omitted, a variable named TEMP 
is used. 

ucbsave is an optional argument specifying a block of 
contiguous words in which to retrieve the interrupting 
device's UCB address. If omitted, a block of 
contiguous words named CNTBL is used. 

Outputs: R4 is the controller index, only if nctlr is greater than 
1. 

R5 is the UCB address. 

Example : 

INTSV$ PP,PR4,P$$P11 

This usage of INTSV$ would effectively replace lines 7 through 26 in 
Figure 4-6. (P$$P11 is a symbol equated to the number of 
controllers. ) 
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CHAPTER 5 
EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



This section contains the Executive routines typically used by I/O 
drivers. They are listed in alphabetical order. The descriptions are 
taken directly from the source code for the associated services. 

We describe only the most widely used subroutines. Many other 
Executive service subroutines are available in modules lOSUB.MAC, 
SYSXT.MAC, QUEUE. MAC, CORAL. MAC, and REQSB.MAC under UIC [11,10]. 



5.1 SYSTEM-STATE REGISTER CONVENTIONS 

In system state, R5 and R4 are, by convention, nonvolatile registers. 
This means that an internally called routine is required to save and 
restore these two registers if the routine destroys their contents. 
R3, R2, Rl, and RO are volatile registers and may be used by a called 
routine without save and restore responsibilities. 

When a driver is entered directly from an interrupt, it is operating 
at interrupt level, not at system state. At interrupt level, any 
register the driver uses must be saved and restored. INTSV? preserves 
R5 and R4 for the driver's use. 

A routine may violate these conventions as long as an explicit 
statement exists in the program preface detailing the departure from 
conventions. Such departures should be avoided; they should be 
employed only when you can demonstrate that a departure from 
convention can improve overall system performance. 

See D.DSP in Section 4.1.2.1 for the contents of registers when a 
driver is entered. 



5.2 CONDITIONAL ROUTINES 

Two of the routines discussed in this chapter (Get Word and Put Word) 
normally are assembled conditionally out of the Executive code. If a 
user-written driver requires either of these routines, the appropriate 
question must be answered affirmatively in the SYSGEN dialog. This 
requirement is spelled out in the descriptions that follow. 



5.3 SERVICE CALLS 

In the following descriptions, the filenames mentioned are source 
modules found on the Executive source disk as [11,10] filename. MAC. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$ACHKB/$ACHCK 



ADDRESS CHECK 

These routines are in the file lOSCJB. A driver may call either 

routine to address-check a task buffer while the task is the current 

task. The Address Check routines are normally used only by drivers 
setting UC.QUE in U.CTL. See Section 6.3 for an example. 

Calling Sequences: 

CALL $ACHKB 
or 

CALL $ACHCK 

Description: 

+ 
**-$ACHKB-ADDRESS CHECK BYTE ALIGNED 
**-$ACHCK-ADDRESS CHECK WORD ALIGNED 

THIS ROUTINE IS CALLED TO ADDRESS CHECK A BLOCK OF MEMORY TO SEE 
WHETHER IT LIES WITHIN THE ADDRESS SPACE OF THE CURRENT TASK. 



jff^^^^^ 



INPUTS: 



RO=STARTING ADDRESS OF THE BLOCK TO BE CHECKED. ^m. 

R1=LENGTH OF THE BLOCK TO BE CHECKED IN BYTES. ^^ 



OUTPUTS : 



C=l IF ADDRESS CHECK FAILED. 
C=0 IF ADDRESS CHECK SUCCEEDED. 

RO AND R3 ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$ALOCB 



ALLOCATE CORE BUFFER 

This routine is in the file CORAL. 

Calling Sequences: 

CALL $ALOCB 

or 

CALL $AL0C1 

+ 
**-$AL0CB-ALL0CATE CORE BUFFER 
**-$ALOCl-ALLOCATE CORE BUFFER (ALTERNATE ENTRY) 

THIS ROUTINE IS CALLED TO ALLOCATE AN EXEC CORE BUFFER. THE 
ALLOCATION ALGORITHM IS FIRST FIT AND BLOCKS ARE ALLOCATED IN 
MULTIPLES OF FOUR BYTES. 



INPUTS! 



RO=ADDRESS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT $AL0C1. 
R1=SIZE OF THE CORE BUFFER TO ALLOCATE IN BYTES. 



OUTPUTS: 



C=l IF INSUFFICIENT CORE IS AVAILABLE TO ALLOCATE THE BLOCK. 
C=0 IF THE BLOCK IS ALLOCATED. 

RO=ADDRESS OF THE ALLOCATED BLOCK. 

R1"LENGTH OF BLOCK ALLOCATED. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$ASUMR 






ASSIGN UNIBUS MAPPING REGISTERS 

This routine is in the file lOSUB. It is used only for PDP-11/70 NPR 
devices requiring UNIBUS Mapping Registers. Normally, it is not 
called directly by an I/O driver. Rather, it is called from within 
the $STMAP routine. Refer to Appendix B for a discussion. 

Calling Sequence: 

CALL $ASUMR 

Description: 



**-$$ASUMR-ASSIGN UNIBUS MAPPING REGISTERS 

THIS ROUTINE IS CALLED TO ASSIGN A CONTIGUOUS SET OF UMR'S. NOTE THAT 
FOR THE SAKE OF SPEED, THE LINK WORD OF EACH MAPPING ASSIGNMENT BLOCK 
POINTS TO THE UMR ADDRESS (2ND) WORD OP THE BLOCK, NOT THE FIRST WORD. 
THE CURRENT STATE OF UMR ASSIGNMENT IS REPRESENTED BY A LINKED LIST OF 
MAPPING ASSIGNMENT BLOCKS, EACH BLOCK CONTAINING THE ADDRESS OF THE 
FIRST UMR ASSIGNED AND THE NUMBER OF UMR'S ASSIGNED TIMES 4. THE 
BLOCKS ARE LINKED IN THE ORDER OF INCREASING FIRST UMR ADDRESS. 

INPUTS : 



R0=POINTER TO A MAPPING REGISTER ASSIGNMENT BLOCK. 
M.UMRN(RO)=NUMBER OF UMR'S REQUIRED * 4. 



w^^^, 



OUTPUTS! 



ALL REGISTERS ARE PRESERVED. 

C=0 IF THE UMR'S WERE SUCCESSFULLY ASSIGNED. 

ALL FIELDS OF THE MAPPING REGISTER ASSIGNMENT BLOCK 

ARE INITIALIZED AND THE BLOCK IS LINKED INTO 

THE ASSIGNMENT LIST. 
C=l IF THE UMR'S COULD NOT BE ASSIGNED. 



^P«TOW- 
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EXECDTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$CLINS 



CLOCK QUEUE INSERTION 

This routine is in the file QUEUE. 

Calling Sequence: 

CALL $CLINS 

Description: 

+ 
**-$CLINS-CLOCK QUEUE INSERTION 

THIS ROUTINE IS CALLED TO MAKE AN ENTRY IN THE CLOCK QUEUE. THE ENTRY 
IS INSERTED SUCH THAT THE CLOCK QUEUE IS ORDERED IN ASCENDING TIME, 
THUS THE FRONT ENTRIES ARE MOST IMMINENT AND THE BACK LEAST. 



INPUTS: 



RO=ADDRESS OF THE CLOCK QUEUE ENTRY CORE BLOCK. 

R1=HIGH ORDER HALF OF DELTA TIME. 

R2=L0W ORDER HALF OF DELTA TIME. 

R4=REQUEST TYPE. 

R5=ADDRESS OF REQUESTING TCB OR REQUEST IDENTIFIER. 



OUTPUTS! 



THE CLOCK QUEUE ENTRY IS INSERTED IN THE CLOCK QUEUE ACCORDING 
TO THE TIME THAT IT WILL COME DUE. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$DEACB 



DEALLOCATE CORE BUFFER 

This routine is in the file CORAL. 

Calling sequences: 

CALL $DEACB 
or 

CALL $DEAC1 

+ 
**-$DEACB-DEALLOCATE CORE BUFFER 
**-$DEACl-DEALLOCATE CORE BUFFER (ALTERNATE ENTRY) 

THIS ROUTINE IS CALLED TO DEALLOCATE AN EXEC CORE BUFFER. THE BLOCK 
IS INSERTED INTO THE FREE BLOCK CHAIN BY CORE ADDRESS. IF AN 
ADJACENT BLOCK IS CURRENTLY FREE, THEN THE TWO BLOCKS ARE MERGED 
AND INSERTED IN THE FREE BLOCK CHAIN. 

INPUTS: 

RO=ADDRESS OF THE CORE BUFFER TO BE DEALLOCATED. 

R1=SIZE OF THE CORE BUFFER TO DEALLOCATE IN BYTES. 

R3=ADDRESS OF CORE ALLOCATION LISTHEAD-2 IF ENTRY AT $DEAC1. ^^. 

OUTPUTS: 

THE CORE BLOCK IS MERGED INTO THE FREE CORE CHAIN BY CORE 
ADDRESS AND IS MERGED IP NECESSARY WITH ADJACENT BLOCKS. 



^™^Wf\ 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$DEUMR 



DEASSIGN UNIBUS MAPPING REGISTERS 

This routine is in the file lOSUB. It is used only for PDP-11/70 NPR 
devices requiring UNIBUS Mapping Registers. Normally, it is not 
called directly by an I/O driver. Rather, it is called from within 
the $IODON routine. Refer to Appendix B for a discussion. 

Calling Sequence: 

CALL $DEUMR 

Description: 



**-$DEUMR-DEASSIGN UNIBUS MAPPING REGISTERS 

THIS ROUTINE IS CALLED TO DEASSIGN A CONTIGUOUS BLOCK OF UMR ' S . IF 
THE MAPPING ASSIGNMENT BLOCK IS NOT IN THE LIST, NO ACTION IS TAKEN. 
NOTE THAT FOR THE SAKE OF ASSIGNMENT SPEED, THE LINK WORD POINTS TO 
THE UMR ADDRESS (2ND) WORD OF THE ASSIGNMENT BLOCK. 

INPUTS: 

R2=P0INTER TO ASSIGNMENT BLOCK. 

OUTPUTS: 

RO AND Rl ARE RESERVED. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$DVMSG 



DEVICE MESSAGE OUTPUT 

Device Message Output is in file lOSUB. 

Calling Sequence: 

CALL $DVMSG 

Description: 

+ 
**-$DVMSG-DEVICE MESSAGE OUTPUT 

THIS ROUTINE IS CALLED TO SUBMIT A MESSAGE TO THE TASK TERMINATION 
NOTIFICATION TASK. MESSAGES ARE EITHER DEVICE RELATED OR A 
CHECKPOINT WRITE FAILURE FROM THE LOADER. 

INPUTS: 

RO=MESSAGE NUMBER. 

R5=ADDRESS OF THE UCB OR TCB THAT THE MESSAGE APPLIES TO. 



OUTPUTS; 



A FOUR WORD PACKET IS ALLOCATED, RO AND R5 ARE STORED IN THE 
SECOND AND THIRD WORDS, RESPECTIVELY, AND THE PACKET IS 
THREADED INTO THE TASK TERMINATION NOTIFICATION TASK MESSAGE 
QUEUE. 

NOTE: IF THE TASK TERMINATION NOTIFICATION TASK IS NOT 

INSTALLED OR NO STORAGE CAN BE OBTAINED, THEN THE 
MESSAGE REQUEST IS IGNORED. 



Note: 



Drivers use only two codes in calling $DVMSG: T.NDNR (device not 
ready) , and T.NDSE (select error) . $DVMSG can be set up and 
called as follows: 

MOV #T.NDNR,RO 

or 

MOV #T.NDSE,RO 
CALL $DVMSG 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$FORK 



FORK 

Fork is in the file SYSXT. A driver calls $FORK to switch from a 
partially interruptable level (its state following a call on $INTSV) 
to a fully interruptable level. 

Calling sequence: 

CALL $FORK 

Description: 

+ 
**_$FORK-FORK AND CREATE SYSTEM PROCESS 

THIS ROUTINE IS CALLED FROM AN I/O DRIVER TO CREATE A SYSTEM PROCESS THAT 
WILL RETURN TO THE DRIVER AT STACK DEPTH ZERO TO FINISH PROCESSING. 



INPUTS : 



R5==ADDRESS OF THE UCB FOR THE UNIT BEING PROCESSED. 



OUTPUTS : 



Notes : 
1. 



REGISTERS R5 AND R4 ARE SAVED IN THE CONTROLLER FORK BLOCK AND 
A SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK 
QUEUE AND A JUMP TO $INTXT IS EXECUTED. 



$FORK cannot be called unless $INTSV has been previously 
called. The fork-processing routine assumes that $INTSV has 
set up entry conditions. 

A driver's current timeout count is cleared in calls to 
$FORK. This protects the driver from synchronization 
problems that can occur when an I/O request and the timeout 
for that request happen at the same time. After a return 
from a call to $FORK, a driver's timeout code will not be 
entered. 

If the clearing of the timeout count is not desired, a driver 
has two alternatives: 

a. Perform timeout operations by directly inserting elements 
in the clock queue (refer to the description of the 
$CLINS routine) . 

b. Perform necessary initialization, including clearing 
S.STS in the SCB to zero (establishing the controller as 
not busy) , and call the $F0RK1 routine rather than $FORK. 
Calling $FORKl bypasses the clearing of the current 
timeout count. 

The driver must not have any information on the stack when 
$FORK is called. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$F0RK1 



FORKl 

Forkl is in the file SYSXT. A driver calls $F0RK1 to bypass the 
clearing of its timeout count when it switches from a partially 
interruptable level to a fully interruptable level (refer also to the 
description of the $FORK routine) . 

Calling Sequence: 

CALL $ FORKl 

Description: 

+ 



**-$FORKl-FORK AND CREATE SYSTEM PROCESS 

THIS ROUTINE IS AN ALTERNATE ENTRY TO CREATE A SYSTEM PROCESS AND 
SAVE REGISTER R5 . 

INPUTS: 

R4=ADDRESS OF THE LAST WORD OF A 3 WORD FORK BLOCK PLUS 2. 
R5=REGISTER TO BE SAVED IN THE FORK BLOCK. 
OUTPUTS : 

REGISTER R5 IS SAVED IN THE SPECIFIED PORK BLOCK AND A SYSTEM JUi 

PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK QUEUE 
AND A JUMP TO $INTXT IS EXECUTED. 

Notes: 



1. For mapped systems with loadable driver support, a 5-word 
fork block is required for calls to $F0RK1. 

2. When a 5-word fork block is used, the driver must initialize 

the fifth word with the base address (in 32-word blocks) of ^iAl 

the driver partition. This address can be obtained from the 
fifth word of the standard fork block in the SCB. 

3. The driver must not have any information on the stack when 
$F0RK1 is called. 
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EXECDTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$GTBYT 



GET BYTE 

Get Byte is in the file BFCTL. Get byte manipulates words U.BUF and 
U.BUF+2 in the UCB. 

Calling sequence: 

CALL $GTBYT 

Description: 

+ 
**-$GTBYT-GET NEXT BYTE FROM USER BUFFER 

THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS BEEN 
FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED. 

INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 

OUTPUTS : 

THE NEXT BYTE IS FETCHED FROM THE USER BUFFER AND RETURNED 
TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS 
INCREMENTED . 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$GTPKT 



M* 7 '^^'^11 ail 



GET PACKET 

Get Packet is in the file lOSUB. 

Calling sequence: 

CALL $GTPKT 

Description: 

+ 
**-$GTPKT-GET I/O PACKET FROM REQUEST QUEUE 

THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O 
REQUEST TO PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY 
SET INDICATION IS RETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO 
DEQUEUE THE NEXT REQUEST FROM THE CONTROLLER QUEUE. IF NO REQUEST 
CAN BE DEQUEUED, THEN A CARRY SET INDICATION IS RETURNED TO THE 
CALLER. ELSE THE CONTROLLER IS SET BUSY AND A CARRY CLEAR 
INDICATION IS RETURNED TO THE CALLER. 

INPUTS: 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET FOR. 



OUTPUTS: 



C=l IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED. ^^ 

C=0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED. 

R1=ADDRESS OF THE I/O PACKET. 

R2=PHYSICAL UNIT NUMBER. 

R3=C0NTR0LLER INDEX. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE UNIT CONTROL BLOCK. 

NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$GTWRD 



GET WORD 

Get Word is in the file BFCTL. It manipulates words U.BUF and U.BUF+2 
in the UCB. Get Word is conditionally assembled. If a user-written 
driver requires this routine, the following question must be answered 
affirmatively in Phase 1 of SYSGEN: 



IS THE EXECUTIVE ROUTINE $GTWRD REQUIRED? [Y/N] : 

This question is asked only if you have answered 
question: 



'yes' 



to the 



ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] ; 

Calling sequence: 

CALL $GTWRD 

Description: 

+ 
**-$GTWRD-GET NEXT WORD FROM USER BUFFER 

THIS ROUTINE IS CALLED TO GET THE NEXT WORD FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE WORD HAS BEEN 
FETCHED, THE NEXT WORD ADDRESS IS CALCULATED. 

INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 

OUTPUTS : 

THE NEXT WORD IS FETCHED FROM THE USER BUFFER AND RETURNED 

TO THE CALLER ON THE STACK. THE NEXT WORD ADDRESS IS CALCULATED. 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$INTSV 



INTERRUPT SAVE 

Interrupt Save is in the file SYSXT. 

Calling sequence: 

CALL $INTSV,PRn 

n has a range of 0-7. 

Description: 

+ 
**-$INTSV-INTERRUPT SAVE 

THIS ROUTINE IS CALLED FROM AN INTERRUPT SERVICE ROUTINE WHEN AN — 

INTERRUPT IS NOT GOING TO BE IMMEDIATELY DISMISSED. A SWITCH TO ^^'. 

THE SYSTEM STACK IS EXECUTED IF THE CURRENT STACK DEPTH IS +1. WHEN 
THE INTERRUPT SERVICE ROUTINE FINISHES ITS PROCESSING, IT EITHER FORKS, 
JUMPS TO $INTXT, OR EXECUTES A RETURN. 

INPUTS: 

4(SP)=PS WORD PUSHED BY INTERRUPT. 

2(SP)=PC WORD PUSHED BY INTERRUPT. 

0(SP)=SAVED R5 PUSHED BY 'JSR R5,$INTSV'. 

0(R5)=NEW PROCESSOR PRIORITY. ,,gl«. 



OUTPUTS: 



REGISTER R4 IS PUSHED ONTO THE CURRENT STACK AND THE CURRENT 
STACK DEPTH IS DECREMENTED. IF THE RESULT IS ZERO, THEN 
A SWITCH TO THE SYSTEM STACK IS EXECUTED. THE NEW PROCESSOR 
STATUS IS SET AND A CO-ROUTINE CALL TO THE CALLER IS EXECUTED. 



Note: 



A system macro, INTSV$ , is provided to simplify the coding of 
standard interrupt entry processing. See Section 4.3. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$INTXT 



INTERRUPT EXIT 

Interrupt Exit is in the file SYSXT. 

Calling sequence: 

JMP $INTXT 

Description: 

+ 
**-$INTXT-INTERRUPT EXIT 

THIS ROUTINE IS CALLED VIA A RETURN TO EXIT FROM AN INTERRUPT. IF THE 

STACK DEPTH IS NOT EQUAL TO ZERO, THEN REGISTERS R4 AND R5 ARE 

RESTORED AND AN RTI IS EXECUTED. ELSE A CHECK IS MADE TO SEE 

IF THERE ARE ANY ENTRIES IN THE FORK QUEUE. IF NONE, THEN R4 AND 

R5 ARE RESTORED AND AN RTI IS EXECUTED. ELSE REGISTERS R3 THRU 

RO ARE SAVED ON THE CURRENT STACK AND A DIRECTIVE EXIT IS EXECUTED. 

INPUTS: (MAPPED SYSTEM) 

06(SP)=PS WORD PUSHED BY INTERRUPT. 
04(SP)=PC WORD PUSHED BY INTERRUPT. 
02(SP)=SAVED R5. 
00(SP)=SAVED R4. 

INPUTS: (REAL MEMORY SYSTEM) 

NONE. 
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EXECOTIVE SERVICES AVAIIJ^BLE TO I/O DRIVERS 



$IOALT/$IODON 






I/O DONE ALTERNATE ENTRY and I/O DONE 

These routines are in the file lOSUB. 

Calling sequences: 

CALL $IOALT 
CALL $IODON 

Description; 

+ 
**-$IOALT-I/0 DONE (ALTERNATE ENTRY) 
**-$IODON-I/0 DONE 

THIS ROUTINE IS CALLED BY DEVICE DRIVERS AT THE COMPLETION OF AN I/O REQUEST 
TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE SET IDLE AND $IOFIN IS 
ENTERED TO FINISH THE PROCESSING. 

INPUTS: 

RO=FIRST I/O STATUS WORD. 

R1=SEC0ND I/O STATUS WORD. 

R2=STARTING AND FINAL ERROR RETRY COUNTS IF ERROR LOGGING DEVICE. 

R5=ADDRESS OF THE UNIT CONTROL BLOCK OF THE UNIT BEING COMPLETED. 

NOTE: IF ENTRY IS AT $IOALT, THEN Rl IS CLEARED TO SIGNIFY THAT THE 
SECOND STATUS WORD IS ZERO. 

OUTPUTS: 

THE UNIT AND CONTROLLER ARE SET IDLE. 

R3=ADDRESS OF THE CURRENT I/O PACKET. 



NOTE 



R4 is destroyed when either of these routines is called. The Jittih 
routine call $IOFIN, which destroys R4., - - . , 

These routines push the address of routine $DQUMR on to the stack 
before returning to the driver. This precludes the use of the 
stack for temporary data storage by divers when calling these 
routines. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$IOFIN 



I/O E'INISH 

I/O Finish is in the file lOSUB. Most drivers do not call I/O Finish, 
but you should be aware that this routine is executed when a driver 
calls $IOALT or $IO,DON. A driver that references an I/O packet before 
it is queued (bit UC.QUE set — see Section 6.3 for an example) calls 
I/O Finish if the driver finds an error while preprocessing the I/O 
packet. 

Calling sequence: 

CALL $IOFIN 

Description: 

; + 

; **-$IOFIN-I/0 FINISH 

; THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE THE UNIT AND 
; CONTROLLER ARE NOT TO BE DECLARED IDLE. 

; INPUTS: 

• RO=FIRST I/O STATUS WORD. 

; R1=SEC0ND I/O STATUS WORD. 

; R3=ADDRESS OF THE I/O REQUEST PACKET. 

; R5=ADDRESS OF THE UNIT CONTROL BLOCK. 

• OUTPUTS: 

; THE FOLLOWING ACTIONS ARE PERFORMED: 

• 1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O STATUS BLOCK IF 

ONE WAS SPECIFIED. 

; 2-THE I/O REQUEST COUNT IS DECREMENTED. IF THE RESULTANT COUNT IS 
; ZERO, THEN ' TS . RDN ' IS CLEARED IN CASE THE TASK WAS 

; STOPPED FOR I/O RUNDOWN. 

; 3-lF 'TS.CKR' IS SET, THEN IT IS CLEARED AND CHECKPOINTING OF THE 
TASK IS INITIATED. 

'; 4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS QUEUED 

• FOR THE TASK. ELSE THE I/O PACKET IS DEALLOCATED. 

; 5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED. 
'; NOTE: R4 IS DESTROYED BY THIS ROUTINE. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$MPUBM 



.i^^ii 



MAP UNIBUS TO MEMORY 

This routine is in the file lOSUB. It is used only for PDP-11/70 NPR 
devices requiring UNIBUS Mapping Registers. See Appendix B for a 
discussion. 

Calling Sequence: 

CALL $MPUBM 

Description: 

+ 
**-$MPUBM-MAP UNIBUS TO MEMORY 

THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO LOAD THE "^^ 

NECESSARY UNIBUS MAP REGISTERS TO EFFECT A TRANSFER TO MAIN MEM- 
ORY ON AN 11/70 PROCESSOR WITH EXTENDED MEMORY. 

INPUTS: 

R4=ADDRESS OF DEVICE SCB. 
R5=ADDRESS OF DEVICE UCB. 

OUTPUTS : 

THE UNIBUS MAP REGISTERS NECESSARY TO EFFECT THE TRANSFER ^^ 

ARE LOADED. 

NOTE: REGISTER R3 IS PRESERVED ACROSS CALL. 
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EXECOTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$MPUB1 



MAP UNIBUS TO MEMORY (ALTERNATE ENTRY) 

This routine is in file lOSUB. It is used only for PDP-11/70 NPR 
devices that require UNIBUS Mapping Registers and support parallel 
operations. See Appendix B for a discussion of using this routine. 

Calling Sequence: 
CALL $MPUB1 



Description: 

+ 
**-$MPUBl-MAP UNIBUS TO MEMORY (ALTERNATE ENTRY) 

THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO LOAD THE 
NECESSARY UNIBUS MAP REGISTERS TO EFFECT A TRANSFER TO MAIN 
MEMORY ON AN 11/70 PROCESSOR WITH EXTENDED MEMORY. THIS ALTERNATE 
ENTRY POINT ALLOWS THE DRIVER TO SPECIFY A NON-STANDARD UMR MAPPING 
ASSIGNMENT BLOCK. 

INPUTS: 

RO=ADDRESS OF A UMR MAPPING ASSIGNMENT BLOCK 

OUTPUTS : 

THE UNIBUS MAP REGISTERS NECESSARY TO EFFECT THE 
TRANSFER ARE LOADED 

NOTE: REGISTER R3 IS PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$PTBYT 



PUT BYTE 

Put Byte is in the file BFCTL, Put Byte manipulates words U.BUF and 
U.BUF+2 in the UCB. 

Calling sequence: 

CALL $PTBYT 

Description: 

+ 
**-$PTBYT-PUT NEXT BYTE IN USER BUFFER 

THIS ROUTINE IS CALLED TO PUT A BYTE IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE BYTE HAS BEEN STORED, THE NEXT BYTE ADDRESS 

IS INCREMENTED. 



INPUTS: 



R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=BYTE TO BE STORED IN THE NEXT LOCATION OF THE USER BUFFER. 



OUTPUTS: 



THE BYTE IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK,. THE NEXT BYTE ADDRESS IS INCREMENTED. 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



$PTWRD 






PUT WORD 

Put Word is in the file BFCTL. It manipulates words U.BUF and U.BUF+2 
in the UCB. Put Word is conditionally assembled. If a user-written 
driver requires this routine, the following question must be answered 
affirmatively in Phase 1 of SYSGEN: 

IS THE EXECUTIVE ROUTINE $PTWRD REQUIRED? [Y/N] : 

This question is asked only if you have answered "yes" to the 
question: 

ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] : 

Calling sequence: 

CALL $PTWRD 

Description: 

+ 
**-$PTWRD-PUT NEXT WORD IN USER BUFFER 

THIS ROUTINE IS CALLED TO PUT A WORD IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD ADDRESS 

IS CALCULATED. 



INPUTS! 



R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=W0RD TO BE STORED IN THE NEXT LOCATION OF THE BUFFER. 



OUTPUTS: 



THE WORD IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK. THE NEXT WORD ADDRESS IS CALCULATED. 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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$QINSP 



QUEUE INSERTION BY PRIORITY 

This routine is in the file QUEUE. A driver may call $QINSP to insert 
into the I/O queue an I/O packet that the Executive has not already 
placed in the queue. Queue Insertion by Priority is used only by 
drivers setting UC.QUE in U.CTL. See Section 6.3 for an example. 

Calling Sequence: 

CALL $QINSP 

Description: 



**-$QINSP-QUEUE INSERTION BY PRIORITY 

THIS ROUTINE IS CALLED TO INSERT AN ENTRY IN A PRIORITY ORDERED 
LIST. THE LIST IS SEARCHED UNTIL AN ENTRY IS FOUND THAT HAS A 
LOWER PRIORITY OR THE END OF THE LIST IS REACHED. THE NEW 
ENTRY IS THEN LINKED INTO THE LIST AT THE APPROPRIATE POINT. 



INPUTS: 



RO=ADDRESS OF THE TWO WORD LISTHEAD. 
R1=ADDRESS OF THE ENTRY TO BE INSERTED. 



OUTPUTS: 

THE ENTRY IS LINKED INTO THE LIST BY PRIORITY. 
RO AND Rl ARE PRESERVED ACROSS CALL. 
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$RELOC i^ 



RELOCATE 

Relocate is in the file lOSUB. A driver may call $RELOC to relocate a 
task virtual address while the task is the current task. Relocate is 
normally used only by drivers setting UC.QUE in U.CTL. See Section 
6.3 for an example. 

Calling Sequence: 

CALL $ RE LOG 

Description: 

+ 
**-SRELOC-RELOCATE USER VIRTUAL ADDRESS 

THIS ROUTINE IS CALLED TO TRANSFORM A 16 BIT USER VIRTUAL ADDRESS 
INTO A RELOCATION BIAS AND DISPLACEMENT IN BLOCK RELATIVE TO APR6 . 

INPUTS : 

RO=USER VIRTUAL ADDRESS TO RELOCATE. 

OUTPUTS: 

Rl=RELOCATION BIAS TO BE LOADED INTO PAR6 . 

R2=DISPLACEMENT IN BLOCK PLUS 140000 (PAR6 BIAS) . 09^, 

RO AND R3 ARE PRESERVED ACROSS CALL. 



:(^^flT% 
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$STMAP 



SET UP UNIBUS MAPPING ADDRESS 

This routine is in the file lOSUB. It is used only for PDP-11/70 NPR 
devices requiring UNIBUS Mapping Registers. See Appendix B for a 
discussion. 

Calling Sequence: 

CALL $STMAP 

Description: 

+ 
**-$STMAP-SET UP UNIBUS MAPPING ADDRESS 

THIS ROUTINE IS CALLED BY UNIBUS NPR DEVICE DRIVERS TO SET UP THE 
UNIBUS MAPPING ADDRESS, FIRST ASSIGNING THE UMR'S. IF THE UMR'S 
CANNOT BE ALLOCATED, THE DRIVER'S MAPPING ASSIGNMENT BLOCK IS PLACED 
IN A WAIT QUEUE AND A RETURN TO THE DRIVER'S CALLER IS EXECUTED. THE 
ASSIGNMENT BLOCK WILL EVENTUALLY BE DEQUEUED WHEN THE UMR'S ARE 
AVAILABLE AND THE DRIVER WILL BE REMAPPED AND RETURNED TO WITH R1-R5 
PRESERVED AND THE NORMAL OUTPUTS OF THIS ROUTINE. THE DRIVER'S 
CONTEXT IS STORED IN THE ASSIGNMENT BLOCK AND FORK BLOCK WHILE IT IS 
BLOCKED AND IN THE WAIT QUEUE. ONCE A DRIVER'S MAPPING ASSIGNMENT 
BLOCK IS PLACED IN THE UMR WAIT QUEUE, IT IS NOT REMOVED FROM THE 
QUEUE UNTIL THE UMR'S ARE SUCCESSFULLY ASSIGNED. THIS STRATEGY 
ASSURES THAT WAITING DRIVERS WILL BE SERVICED FIFO AND THAT DRIVER'S 
WITH LARGE REQUESTS FOR UMR'S WILL NOT WAIT INDEFINITELY. 



INPUTS: 



R4=ADDRESS OF DEVICE SCB. 
R5=ADDRESS OF DEVICE UCB. 
{SP)=RETURN TO DRIVER'S CALLER. 



OUTPUTS: 



UNIBUS MAP ADDRESSES ARE SET UP IN THE DEVICE UCB AND THE 
ACTUAL PHYSICAL ADDRESS IS MOVED TO THE SCB. 

NOTE: REGISTERS Rl , R2 , AND R3 ARE PRESERVED ACROSS CALL. 



NOTE 

This routine pushes the address of 
routine $D0UMR+2 on to the stack before 
returning to the caller. A driver, 
therefore, should not use the stack for 
temporary data storage when calling this 
routine. 
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$STMP1 



j^HB^P^sk 



SET UP UNIBUS MAPPING ADDRESS (ALTERNATE ENTRY) 

This routine is in file lOSUB. It is used only for PDP-11/70 NPR 
devices that require UNIBUS Mapping Registers and support parallel 
operations. See Appendix B for a discussion of using this routine. 

Calling Sequence: 

CALL $STMP1 

Description: 



**-$STMPl-SET UP UNIBUS MAPPING ADDRESS (ALTERNATE ENTRY) 

THIS ENTRY CODE SETS UP AN ALTERNATE DATA STRUCTURE USED AS 
A UMR MAPPING ASSIGNMENT BLOCK AND CONTEXT STORAGE BLOCK, IN 
THE SAME MANNER AS $STMAP USES THE FORK BLOCK AND MAPPING 
BLOCK IN THE SCB. THE FORMAT OF THE STRUCTURE IS AS FOLLOWS: 



^■Hj^ 



4 WORDS USED FOR SAVING 
DRIVER'S CONTEXT IN CASE 
UMR'S CAN'T BE MAPPED 
IMMEDIATELY. 



6 WORDS USED AS A UMR 
MAPPING ASSIGNMENT BLOCK, 



^l^^pli. 



INPUTS: 



RO=ADDRESS OF THE DATA STRUCTURE DEPICTED ABOVE 
R4=ADDRESS OF DEVICE SCB 
R5=ADDRESS OF DEVICE UCB 



OUTPUTS : 



DATA STRUCTURE POINTERS SET UP FOR ENTRY TO $STMP2 IN $STMAP 



NOTE 

This routine pushes the address of 
routine $DQUMR+2 on to the stack before 
returning to the caller. A driver, 
therefore, should not use the stack for 
temporary data storage when calling this 
routine. 
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CHAPTER 6 
INCLUDING A OSER-WRITTEN DRIVER — TWO EXAMPLES 



The first example that follows is a complete illustration of the 
procedures required to add a resident driver and resident data base to 
an RSX-llM system to run on a system without support for loadable 
drivers and without multiuser protection. The driver in the example 
supports the punch capability of the PCll Paper Tape Reader/Punch. 

Section 6.3 gives a coding example from a resident driver that 
inhibits the automatic packet queuing in QIO processing to 
address-check and relocate a special user buffer. 

In addition to the examples shown in this chapter, you should review 
the source code for one or more standard DIGITAL-supplied drivers. 
Also, examine file SYSTB.MAC, which contains SYSGEN created data 
structures. 



6.1 DEVICE DESCRIPTION 

The PCll Paper Tape Reader/Punch is capable of reading 8-hole, 
unoiled, perforated paper tape at 300 character s-per-second, and 
punching tape at 50 characters-per-second. The system consists of a 
Paper Tape Reader/Punch and Controller. A unit containing only a 
reader (PRll) is also available. 

In reading tape, a set of photodiodes translates the presence or 
absence of holes in the tape to logic levels representing I's and O's. 
In punching tape, a mechanism translates logic levels representing I's 
and O's to the presence or absence of holes in the tape. Any 
information read or punched is parallel-transferred through the 
Controller. When an address is placed on the UNIBUS, the Controller 
decodes the address and determines if the reader or punch has been 
selected. If one of the four device-register addresses has been 
selected, the Controller determines whether an input or an output 
operation should be performed. An input operation from the reader is 
initiated when the processor transmits a command to the Paper Tape 
Reader status register. An output operation is initiated when the 
processor transfers a byte to the Paper Tape Punch buffer register. 

The Controller enables the PDP-11 System to control the reading or 
punching of paper tape in a flexible manner. The reader can be 
operated independently of the punch; either device can be under 
direct program control or can operate without direct supervision, 
through the use of interrupts, to maintain continuous operation. 
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6.2 DATA BASE AND DRIVER SOURCE 

The simplicity of writing a conventional driver for RSX-llM is 
obscured by the volume of explanation required to cover the universal 
case. As you will see below, in a particular case, building a 
conventional driver is a straightforward and modest undertaking. 






6.2.1 The Data Base 

The resident data base source shown below is self-explanatory. Take 
special note of the legal function mask words, starting at line 45. 
The standard function codes listed in Table 4-1 were used in creating 
the mask. Thus, the Punch driver accepts the following I/O functions: 

Cancel I/O 

Write Logical Block 

Attach Device 

Detach Device 

Access File For Read/Write 

Access File For Read/Write/Extend 

Deaccess File 

Write Virtual Block 



Cancel I/O is mandatory. Write Logical Block 
function actually supported. 



is the only transfer 



Attach/Detach are control functions. The three Access/Deaccess 
functions are legal for FCS and RMS compatibility, but are no-op'ed. 
Write Virtual Block is legal but is converted to Write Logical Block 
by QIO directive processing. 

The Bit Mask for each function is as follows: 



FUNCTION Fl 


JNCTION 


CAN 





WLB 


1 


ATT 


3 


DET 


4 


ACW 


16 


ACE 


17 


DAC 


20 


WVB 


22 



FUNCTION CODE (OCTAL) MASK (OCTAL) BIT RANGE (DECIMAL) 



000001 


0-15. 


000002 


0-15. 


000010 


0-15. 


000020 


0-15. 


040000 


0-15. 


100000 


0-15. 


000001 


16.-31 


000004 


16.-31 



The legal masks result from adding the 0-15(10) bit-range words to 
form a mask and all the 16-31(10) bit-range words to form the second 
mask. 

The control, no-op, and ACP masks are created in an analogous fashion, 
matching bit positions with legal function-code meanings. 

The complete set of mask words appears on lines 45 through 52 in the 
data-structure source. 

The function code selections for record-oriented devices are intended 
to match FCS and RMS requirements for file-structured devices. When 
FCS or RMS executes an Access For Write, it is simply marked a no-op. 
This tends to minimize FCS and RMS device-dependent logic. 
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Note also on line 84 that the controller number, which is encoded in 
the low byte of the interrupt vector PS word in RSX-llM, is set "to 
zero. Finally, since the code represents a resident data base, note 
that lines 78 through 85 would be omitted for a loadable data base. 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 



.TITLE IJSRTB 
.IDENT /Ol/ 



COPYRIGHT 1976, DIGITAL EQUIPMENT CORP., MAYNARD , MASS. 

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

VERSION 01 

T. J. PASCUSNIK 25-NOV-74 

CONTROL BLOCKS FOR PAPER TAPE PUNCH DRIVER 

MACRO LIBRARY CALLS 



.MCALL DCBDF$,HWDDF$ 

DCBDF$ 

HWDDF$ 



;DEFINE DEVICE CONTROL BLOCK OFFSETS* 
; DEFINE HARDWARE REGISTERS 



PAPER TAPE PUNCH DEVICE DATA BASE 
PAPER TAPE PUNCH DEVICE CONTROL BLOCK 



$USRTB: : 
PPDCB: 



. WORD 

.WORD .PPO 

.ASCII /PP/ 

.BYTE 0,0 



.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 



PPND-PPST 

$PPTBL 

140033 

30 

140000 



5 



1 

4 



LINK TO NEXT DCB 

POINTER TO FIRST UCB 

DEVICE NAME 

LOWEST AND HIGHEST UNIT NUMBERS COVERED 

BY THIS DCB 
LENGTH OF EACH UCB IN BYTES 
POINTER TO DRIVER DISPATCH TABLE 
LEGAL FUNCTION MASK CODES 0-15. 
CONTROL FUNCTION MASK CODES 0-15. 
NO-P'ED FUNCTION MASK CODES 0-15. 
ACP FUNCTION MASK CODES 0-15. 
LEGAL FUNCTION MASK CODES 16.-31. 
CONTROL FUNCTION MASK CODES 16.-31. 
NO-OP 'ED FUNCTION MASK CODES 16.-31. 
ACP FUNCTION MASK CODES 16.-31. 



PAPER TAPE PUNCH UNIT CONTROL BLOCK 



.PPO: 

PPST= 



.WORD 
.WORD 
.BYTE 



PPDCB 

.-2 

UC.ATT,0 



BACK POINTER TO DCB 
POINTER TO REDIRECT UNIT UCB 
CONTROL PROCESSING FLAG (PASS CONTROL 
ON ATTACH/DETACH) , UNIT STATUS 



* Appendix C lists all macros 
control block offsets. 



that exist in RSX-llM to generate 
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62 






.BYTE 


0,0 


63 






.WORD 


DV.REC 


64 










65 






.WORD 





66 










67 






.WORD 





68 










69 






.WORD 


64. 


70 










71 






.WORD 


PPSCB 


72 






.WORD 





73 






.BLKW 


1 


74 










75 






.BLKW 


1 


76 






.BLKW 


1 


77 


PPND= . 






78 


! 








79 


I 


PAPER 


TAPE PUNCH INTERR 


80 


! 








81 






.ASECT 




82 


.' 


= 74 






83 






.WORD 


$PPINT 


84 






• WORD 


PR710 


85 






.PSECT 




86 










87 




PAPER 


TAPE PUNCH STATUS 


88 










89 


PPSCB: 


.WORD 





90 










91 






.WORD 


.-2 


92 






.BYTE 


PR4,74/4 


93 






.BYTE 


0,4 


94 






.BYTE 


0,0 


95 










96 






.WORD 


177554 


97 






.BLKW 


1 


98 






.BLKW 


4 


99 










100 






.END 





PHYSICAL UNIT NUMBER, UNIT STATUS EXTENSION 
FIRST DEVICE CHARACTERISTICS WORD 

(RECORD-ORIENTED DEVICE) 
SECOND DEVICE CHARACTERISTICS WORD 

(FOR INTERNAL USE BY DRIVER) 
THIRD DEVICE CHARACTERISTICS WORD 

(FOR INTERNAL USE BY DRIVER) 
FOURTH DEVICE CHARACTERISTICS WORD 

(DEFAULT BUFFER SIZE IN BYTES) 
POINTER TO SCB 

TCB ADDRESS OF ATTACHED TASK 
RELOCATION BIAS OF BUFFER OF CURRENT 

I/O REQUEST 
ADDRESS OF BUFFER OF CURRENT I/O REQUEST 
BYTE COUNT OP CURRENT I/O REQUEST 



.^ffit^R^Vjt 



/ADDRESS OF INTERRUPT ROUTINE 

; INTERRUPT AT PRIORITY 7 (CONTROLLER=0) 



CONTROLLER I/O QUEUE LISTHEAD 

(POINTER TO FIRST ENTRY) 

(POINTER TO LAST ENTRY) 
DEVICE PRI, INTERRUPT VECTOR ADDRESS/4 
CURRENT AND INITIAL TIMEOUT COUNTS 
CONTROLLER INDEX AND STATUS 

{0=IDLE, 1=BUSY) 
ADDRESS OP CONTROL STATUS REGISTER 
ADDRESS OP CURRENT I/O PACKET 
FORK BLOCK ALLOCATION 



4^^f!^, 



6.2.2 Driver Code 

The code shown below for the punch capability of the PCll is typical 

for a conventional driver. In fact, many of the descriptive comments 

can be used as a template and easily tailored to a driver for another 
device . 

The structure of the driver follows the classic RSX-llM form, being 
separated into processing code for: 

Initiator 

Power Failure 

Interrupt 

Timeout 

Cancel I/O 

The driver itself services only Write Logical, Attach, and Detach I/O 
functions. Attach and Detach result in the punching of 170(10) nulls 
each for header and trailer. 

Power Failure and Cancel I/O are handled by means of device timeout, 
as is the device-not-ready condition. 



jl^^lt 



1ffB!B^r| 



6-4 



INCLUDING A USER-WRITTEN DRIVER — TWO EXAMPLES 



The PP driver uses the following Executive services: 

$INTXT 
$GTPKT 
$GTBYT 
$DVMSG 

$INTSV is used indirectly; it is called by INTSV$ (line 165) 
Section 4.3. 



See 



Comments beginning with " ; ; ; ' indicate that the instruction is being 
executed at a priority level greater than or equal to 4. 

The code contained in lines 139-141 is used to inhibit the punching of 
a trailer on ATT/DET if the task is being aborted. This is especially 
desirable when the device is not ready (for example, out of paper 
tape) and the system has generated the detach for the aborting 
process. 



1. 

2. 

3. 

4. 

5. 

6. 

7. 

8. 

9. 
10. 
11. 
12. 
13. 
14. 
15. 
16. 
17. 
18. 
19. 
20. 
21. 
22. 
23. 
24. 
25. 
26. 
27. 
28. 
29. 
30.' 
31. 
32. 
33. 
34. 
35. 
36. 
37. 
38. 
39. 
40. 
41. 
42. 
43. 
44. 
45. 
46. 
47. 
48. 
49. 
50. 



.TITLE PPDRV 
.IDENT /02/ 

COPYRIGHT 1976, DIGITAL EQUIPMENT CORP., MAYNARD , MASS. 

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

VERSION 02 

T. .1. PASCUSNIK 25-NOV-74 

MODIFIED BY: 

C. A. ANDERS 15-MAR-76 

CAOOl — ADDITION OF LOADABLE DRIVER SUPPORT. 
T. J. PASCUSNIK 4-APR-76 

TP031 — EXECUTIVE DATA STRUCTURE CHANGES. 

PCll PAPER TAPE PUNCH DRIVER 
MACRO LIBRARY CALLS 

.MCALL ABODF$ ,HWDDF$ ,PKTDF$ ,TCBDF$ 

ABODF$ {DEFINE TASK ABORT CODES 

HWDDF$ ; DEFINE HARDWARE REGISTER SYMBOLS 

PKTDF$ ; DEFINE I/O PACKET OFFSETS 

TCBDF$ jDEFINE TASK CONTROL BLOCK OFFSETS 

EQUATED SYMBOLS 

PAPER TAPE PUNCH STATUS WORD BIT DEFINITIONS (U.CW2) 
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51. 

52. 

53. 

54. 

55. 

56. 

57. 

58. 

59. 

60. 

61. 

62. 

63. 

64. 

65. 

66. 

67. 

68. 

69. 

70. 

71. 

72. 

73. 

74. 

75. 

76. 

77. 

78. 

79. 

80. 

81. 

82. 

83. 

84. 

85. 

86. 

87. 

88. 

89. 

90. 

91. 

92. 

93. 

94. 

95. 

96. 

97. 

98. 

99. 
100. 
101. 
102. 
103. 
104. 
105. 
106. 
107. 
108. 
109. 
110. 
111. 
112. 
113. 
114. 
115. 
116. 
117. 
118. 
119. 
120. 
121. 
122. 
123. 



WAIT=100000 
ABORT=40000 
TRAIL=200 



; WAITING FOR DEVICE TO COME ON-LINE (1=YES) 
; ABORT CURRENT I/O REQUEST (1=YES) 
.-CURRENTLY PUNCHING TRAILER (1=YES) 



LOCAL DATA 

CONTROLLER IMPURE DATA TABLES (INDEXED BY CONTROLLER NUMBER) 



CNTBL: .BLKW P$$Pll 

.IF GT PS$P11-1 
TEMP: .BLKW 1 
.ENDC 

DRIVER DISPATCH TABLE 



;ADDRESS OF UNIT CONTROL BLOCK 



; TEMPORARY STORAGE FOR CONTROLLER NUMBER 



$PPTBL: : 



.WORD PPINI 

.WORD PPCAN 

.WORD PPOUT 

. WORD PPPWF 



; CAOOl 
; CAOOl 



; DEVICE INITIATOR ENTRY POINT 
; CANCEL I/O OPERATION ENTRY POINT 
; DEVICE TIMEOUT ENTRY POINT 
jPOWERFAIL ENTRY POINT 



^^^K 



**-PPINI-PCll PAPER TAPE PUNCH CONTROLLER INITIATOR 

THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST 
IS QUEUED AND AT THE END OF A PREVIOUS I/O OPERATION TO PROPAGATE THE EXECU- 
TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMPT 
IS MADE TO DEQUEUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS 
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPER- 
ATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED. 

INPUTS: 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 

OUTPUTS : 

IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT- 
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPER- 
ATION IS INITIATED. 



. ENABL LSB 
PPINI: CALL $GTPKT 
BCS PPPWF 



;GET AN I/O PACKET TO PROCESS 

;IF CS CONTROLLER BUSY OR NO REQUEST 



THE FOLLOWING ARGUMENTS ARE RETURNED BY $GTPKT: 

R1=ADDRESS OF THE I/O REQUEST PACKET. 

R2=PHYSICAL UNIT NUMBER OF THE REQUEST UCB. 

R3=C0NTR0LLER INDEX. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE Uc THE CONTROLLER TO BE INITIATED. 

PAPER TAPE PUNCH I/O REQUEST PACKET FORMAT: 

WD. 00 — I/O QUEUE THREAD WORD. 

WD. 01 — REQUEST PRIORITY, EVENT FLAG NUMBER. 

WD. 02 — ADDRESS OF THE TCB OF THE REQUESTER TASK. 

WD. 03 — POINTER TO SECOND LUN WORD IN REQUESTER TASK HEADER. 

WD. 04 — CONTENTS OF THE FIRST LUN WORD IN REQUESTER TASK HEADER (UCB) 

WD. 05 — I/O FUNCTION CODE (lO.WLB, 10. ATT OR lO.DET). 

WD. 06 — VIRTUAL ADDRESS OF I/O STATUS BLOCK. 

WD. 07 — RELOCATION BIAS OF I/O STATUS BLOCK. 
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124. 
125. 
126. 
127. 
128. 
129. 
130. 
131. 
132. 
133. 
134. 
135. 
136. 
137. 
138. 
139. 
140. 
141. 
142. 
143. 
144. 
145. 
146. 
147. 
148. 
149. 
150. 
151. 
152. 
153. 
154. 
155. 
156. 
157. 
158. 
159. 
160. 
161. 
162. 
163. 
164. 
165. 
166. 
167. 
168. 
169. 
170. 
171. 
172. 
173. 
174. 
175. 
176. 
177. 
178. 
179. 
180. 
181. 
182. 
183. 
184. 
185. 
186. 
187. 
188. 
189. 
190. 
191. 
192. 
193. 
194. 
195. 
196. 
197. 



WD. 10 — I/O STATUS BLOCK ADDRESS (REAL OR DISPLACEMENT + 140000) 

WD. 11 — VIRTUAL ADDRESS OF AST SERVICE ROUTINE. 

WD. 12 — RELOCATION BIAS OF I/O BUFFER. 

WD. 13 — BUFFER ADDRESS OF I/O TRANSFER. 

WD. 14 — NUMBER OF BYTES TO BE TRANSFERED. 

WD. 15 — NOT USED. 

WD. 16 — NOT USED. 

WD. 17 — NOT USED. 

WD. 20 — NOT USED. 



10$: 
20$: 



MOV R5,CNTBL(R3) 

CLR U.CW2(R5) 

CMPB I.FCN+1 (Rl) ,#I0 

BEQ 10$ 

MOV I.TCB(R1),R0 

BIT #T2.ABO,T.ST2(R0 

BNE 65$ 

BIS #TRAIL,U.CW2(R5) 

MOV #170. ,U.CNT(R5) 

BIS #WAIT,U.CW2(R5) 

TST @S.CSR(R4) 

BMI 80$ 

BIC #WAIT,U.CW2(R5) 

MOVE S.ITM(R4) ,S.CTM( 

MOV #100,@S.CSR(R4) 



;SAVE UCB POINTER FOR INTERRUPT ROUTINE 

; CLEAR ALL SWITCHES 

WLB/256. ;WRITE LOGICAL BLOCK FUNCTION? 

;IF EQ YES 

;GET REQUESTOR TCB ADDRESS 

) ;TASK BEING ABORTED? ; TP031 

;IF NE YES - DON'T PUNCH TRAILER 
; OTHERWISE FUNCTION IS ATTACH OR DETACH 
; SET FLAG TO PUNCH TRAILER 

;SET COUNT FOR 170 NULLS 

;ASSUME WAIT FOR DEVICE OFF LINE 

.•DEVICE OFF LINE? 

;IF MI YES 

;DEVICE ON LINE, CLEAR WAIT CONDITION 

R4) ;SET TIMEOUT COUNT 

; ENABLE INTERRUPTS 



POWERPAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND THEREFORE CAUSES 
NO IMMEDIATE ACTION ON THE DEVICE. THIS IS DONE TO AVOID A RACE CONDITION 
THAT COULD EXIST IN RESTARTING THE I/O OPERATION 



PPPWF: RETURN 



**-$PPINT-PCll PAPER TAPE PUNCH CONTROLLER INTERUPTS 



$PPINT: 



30$; 

40$ 
50$ 
60$ 



65$: 
70$: 



INTSV$ 


PP,PR4,P$$P11 


MOV 


U.SCB(R5) ,R4 


MOVE 


S.ITM(R4) ,S.CTM 


MOV 


S.CSR(R4) ,R4 


MOV 


(R4)+,U.CW3(R5) 


BMI 


60$ 


SUE 


#1,U.CNT(R5) 


BCS 


50$ 


TSTB 


U.CW2(R5) 


BPL 


30$ 


CLRB 


(R4) 


BR 


40$ 


CALL 


$GTBYT 


MOVE 


(SP)+,(R4) 


JMP 


$INTXT 


INC 


U.CNT(R5) 


CLR 


-(R4) 


CALL 


$FORK 


MOV 


U.SCB(R5) ,R4 


MOV 


S.PKT(R4) ,R1 


MOV 


I.PRM+4(R1) ,R1 


SUB 


U.CNT(R5) ,R1 


MOV 


#IS.SUC&377,R0 


TST 


U.CW3(R5) 


BPL 


70$ 


MOV 


#IE.VER&377,R0 


CALL 


$IODON 


BR 


PPINI 



; ;REF LABEL 

;;GENERATE INTERRUPT SAVE CODE ; CAOOl 
;;GET ADDRESS OF STATUS CONTROL BLOCK 
(R4) ;;, -RESET TIMEOUT COUNT 

POINT R4 TO CONTROL STATUS REGISTER 

SAVE STATUS 

IF MI, ERROR 

DECREMENT CHARACTER COUNT 

IF CS, THEN DONE 

CURRENTLY PUNCHING TRAILER? 

IF PL NO 

LOAD NULL INTO OUTPUT REGISTER 

BRANCH TO LOAD IT 

GET NEXT BYTE FROM USER BUFFER 

LOAD BYTE INTO OUTPUT REGISTER 

EXIT FROM INTERRUPT 

RESET BYTE COUNT 

DISABLE PUNCH INTERRUPTS 

CREATE SYSTEM PROCESS 
POINT R4 TO SCB 
POINT Rl TO I/O PACKET 

AND PICK UP CHARACTER COUNT 
CALCULATE CHARACTERS TRANSFERRED 
ASSUME SUCCESSFUL TRANSFER 
DEVICE ERROR? 
IF PL NO 

UNRECOVERABLE HARDWARE ERROR CODE 
INITIATE I/O COMPLETION 
BRANCH BACK FOR NEXT REQUEST 



DEVICE TIMEOUT RESULTS IN A NOT READY MESSAGE BEING PUT OUT 4 TIMES A 
MINUTE. TIMEOUTS ARE CAUSED BY POWERFAILURE AND PUNCH FAULT CONDITIONS. 
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INCLUDING A USER-WRITTEN DRIVER—TWO EXAMPLES 



198. 








199. 


PPOUT: 


CLRB 


(as.CSR(R4) 


200. 




CLRB 


PS 


201. 


80$: 


MOV 


#IE.DNRS,377,R0 


202. 




MOV 


U.CW2(R5) ,R1 


203. 




BPL 


70$ 


204. 




MOV 


#IE.ABO&377,R0 


205. 




ASL 


Rl 


206. 




BMI 


70$ 


207. 




TST 


@S.CSR(R4) 


208. 




BPL 


20$ 


209. 




MOV 


#T.NDNR,R0 


210. 




MOVE 


#1,S.CTM(R4) 


211. 




DECB 


S.STS(R4) 


212. 




BNE 


PPPWF 


213. 




MOVB 


#15.,S.STS(R4) ; 


214. 




CALLR 


$DVMSG 


215. 




.DSABL 


LSB 


216. 








217. 


; 






218. 


; CANCEL 


I/O OPERATION-FORCE I/O T 


219. 


; 






220. 








221. 


PPCAN : 


CMP 


R1,I.TCB(R0) 


222. 




BNE 


10$ 


223. 




BIS 


# ABORT, U.CW2(R5) 


224. 


10$: 


RETURN 




225. 








226. 




.END 





;, -DISABLE PUNCH INTERRUPT 
;; ALLOW INTERRUPTS 
ASSUME DEVICE NOT READY ERROR 
ARE WE WAITING FOR DEVICE READY? 
IF PL NO, TERMINATE I/O REQUEST 
ASSUME REQUEST IS TO BE ABORTED 
ABORT REQUEST? 
IF MI YES 
PUNCH READY? 
IF PL YES 

SET FOR NOT READY MESSAGE 
SET TIMEOUT FOR 1 SECOND 
TIME TO OUTPUT MESSAGE? 
IF NE NO 
;SET TO OUTPUT NEXT MESSAGE IN 15. SECONDS 
; OUTPUT MESSAGE AND RETURN 



REQUEST FOR CURRENT TASK? 

IF NE NO 

;SET FOR ABORT IF DEVICE NOT READY 



6.3 HANDLING SPECIAL USER BUFFERS 

Some drivers need to handle user buffers in addition to the buffer 
that the Executive address-checks and relocates in a normal transfer 
request. Address-checking and relocation operations must take place 
in the context of the task issuing the I/O request, because the 
mapping registers are set for the issuing task. However, in the 
normal driver interface, the task context after the call to $GTPKT is 
not, in general, that of the issuing task. 

Thus, drivers that need to handle special buffers must be able to 
reference the I/O packet before it is queued, while the context of the 
issuing task is still intact. 

The following coding excerpts from a standard RSX-llM driver (the 
AFCll driver) illustrate the handling of a special user buffer. The 
key points are: 

1. The UC.QUE bit has been set in the control byte (U.CTL) of 
the UCB for each device/unit. (This is not shown in the 
coding excerpts below.) 

2. The routine that is referenced as the initiator entry point 
in the driver dispatch table performs the following actions: 



a. Picks up the user 
address-checks it. 



virtual address and conditionally 



.^^, 



b. Relocates the virtual address, storing the result back 
into the packet. 

c. Inserts the packet into the I/O queue and falls through 
to the entry point AFINI, which calls $GTPKT. 

The driver propagates its own execution by branching back to 
AFINI to call $GTPKT. 
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INCLUDING A USER-WRITTEN DRIVER — TWO EXAMPLES 



DRIVER DISPATCH TABLE 



$AFTBL: 



; .WORD AFCHK 

.WORD AFCAN 

•WORD AFOUT 

.WORD AFPWF 



; DEVICE INITIATOR ENTRY POINT 
; CANCEL I/O OPERATION ENTRY POINT 
; DEVICE TIMEOUT ENTRY POINT 
•POWERFAIL ENTRY POINT 



**-AFCHK-AFCll ANALOG TO DIGITAL CONVERTER CONTROLLER PARAMETER CHECKING 

THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST 

IS RECEIVED FOR THE AFCll ANALOG TO DIGITAL CONVERTOR. AFCll I/O REQUESTS 

CONTAIN DEVICE DEPENDENT INFORMATION THAT MUST BE CHECKED IN THE CONTEXT 

OF THE ISSUING TASK. THEREFORE THE I/O REQUEST IS NOT QUEUED BEFORE CALLING 
THIS DRIVER. 



INPUTS: 



R1=ADDRESS OF THE I/O REQUEST PACKET. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE UCB OF THE CONTROLER TO BE INITIATED. 



OUTPUTS: 



THE CONTROL BUFFER IS ADDRESS CHECKED TO DETERMINE WHETHER IT LIES 
WITHIN THE ISSUING TASK'S ADDRESS SPACE. IF THE ADDRESS CHECK 
SUCCEEDS, THEN THE CONTROL BUFFER ADDRESS IS RELOCATED AND STORED 
IN THE I/O PACKET, THE I/O PACKET IS INSERTED IN THE CONTROLLER 
QUEUE, AND THE DEVICE INITIATOR IS ENTERED TO START THE CONTROLLER. 
ELSE AN ILLEGAL BUFFER STATUS IS ^RETURNED AS THE FINAL I/O STATUS 
OF THE REQUEST. 



AFCHK: 


MOV 


R1,R3 




MOV 


I.PRM+6(R3) ,R0 




.IF DF 


A$$CHK!M$$MGE 




MOV 


I.PRM+4(R3) ,R1 




CALL 


$ACHCK 




BCC 


10$ 




MOV 


#IE.SPC&377,R0 




CALLR 


$IOFIN 




.ENDC 




10$: 


CALL 


$RELOC 




MOV 


R1,I.PRM+6(R3) 




MOV 


R2,I.PRM+10(R3) 




MOV 


R3,R1 




MOV 


R4,R0 




CALL 


$QINSP 



;COPY ADDRESS OF I/O PACKET 

;GET VIRTUAL ADDRESS OF CONTROL BUFFER 



;SET LENGTH OF BUFFER TO CHECK 
.-ADDRESS CHECK CONTROL BUFFER 
;IF CC ADDRESS OKAY 
;SET ILLEGAL BUFFER STATUS 
; FINISH I/O OPERATION 



.-RELOCATE CONTROL BUFFER ADDRESS 

,-SET RELOCATION BIAS OF CONTROL BUFFER 

;SET ADDRESS OF CONTROL BUFFER 

,-SET ADDRESS OF I/O PACKET 

,-SET ADDRESS OF I/O QUEUE LISTHEAD 

; INSERT I/O PACKET IN REQUEST QUEUE 



**-AFINI-AFCH ANALOG TO DIGITAL CONVERTOR CONTROLLER INITIATOR 

THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST 
IS QUEUED AND AT THE END OF A PREVIOUS I/O OPERATION TO PROPAGATE THE EXECU- 
TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMPT 
IS MADE TO DEQUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS 
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPER- 
ATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED. 

INPUTS: 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 

OUTPUTS: 

IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT 
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPER- 
ATION IS INITIATED. 
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INCLUDING A USER-WRITTEN DRIVER — TWO EXAMPLES 



.ENABL LSB 
AFINI: CALL $GTPKT 

BCS APCAN 



GET AN I/O PACKET TO PROCESS 

IF CS CONTROLLER BUSY OR NO REQUEST 

I/O CANCEL (AFCAN) IS A NO-OP FOR AFCll 



CALL $IODON 

BR AFINI 



; FINISH I/O OPERATION 
;G0 AGAIN 






^PiPi^^lk 



J^^^ 
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APPENDIX A 
DEVELOPMENT OF THE ADDRESS DOUBLEWORD 



A . 1 INTRODUCTION 

RSX-llM can be generated as a mapped or an unmapped system. Mapped 
systems can accommodate configurations whose maximum physical memory 
is 4096K bytes. Individual tasks, however, are limited to 64K bytes. 
The addressing in a mapped system is accomplished by using virtual 
addresses and memory mapping hardware. I/O transfers, however, use 
physical addresses 18 bits in length. Since the PDP-11 word size is 
16 bits, some scheme is necessary to represent an address internally 
until it is actually used in an I/O operation. The choice was made to 
encode 2 words as the internal representation of a physical address, 
and to transform virtual addresses for I/O operations into the 
internal doubleword format. 



A. 2 CREATING THE ADDRESS DOUBLEWORD 

For unmapped systems, the doubleword is simply a word of zeros 
followed by a word containing the real address. 

On receipt of a QIO directive for mapped systems, the buffer address 
in the DPB, which contains a task virtual address, is converted to 
address doubleword format. 

The virtual address in the DPB is structured as follows: 

Bits 0-5 Displacement in terms of 32-word blocks 

Bits 6-12 Block number 

Bits 13-15 Page Address Register Number (PAR#) 

The internal RSX-llM translation restructures this virtual address 
into an address doubleword as follows: 

The relocation base contained in the PAR specified by the PAR# in the 
virtual address in the DPB is added to the block number in the virtual 
address. The result becomes the first word of the address doubleword. 
It represents the nth 32-word block in a memory viewed as a collection 
of 32-word blocks. Note that at the time the address doubleword is 
computed, the user Issuing the QIO directive is mapped into the 
processor's memory management registers. 
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DEVELOPMENT OF THE ADDRESS DODBLEWORD 

The second word is formed by placing the displacement in block (bits 
0-5 of virtual address) into bits 0-5. The block number field was 
accommodated in the first word and bits 6-12 are cleared. Finally, a 
6 is placed in bits 13-15 to enable use of PAR #6, which the Executive 
uses to service I/O for program transfer devices. 

For non-processor request (NPR) devices, the driver requirements for 
manipulating the address doubleword are direct and are discussed with 
the description of U.BUF in Section 4.1.4.1. 



i^^^i 
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APPENDIX B 
PDP-11/70 DRIVERS FOR HPR DEVICES 



Special features must be built into drivers for non-MASSBUS NPR 
(non-processor request) devices attached to a PDP-11/70 with 
extended-memory support (22-bit addressing) . 

Non-MASSBUS NPR devices on the 11/70 must perform I/O transfers via 
UNIBUS Mapping Registers (UMRs) as described in the PpP-ll/7p 
Processor Handbook . One UMR is required for each 4K words involved in 
the transfer— as specified by the contents of U.CNT in the UCB. When 
multiple UMRs are required for a transfer, they must be contiguous. 

A driver can be assigned UMRs through one of three procedures. These 
procedures involve: 

1. Dynamically allocating UMRs for the duration of the data 
transfer, or 

2. Dynamically allocating UMRs for longer periods of time, or 

3. Statically allocating UMRs during system generation. 

NOTE 

In large systems, use of the second and 
third procedures above to hold UMRs for 
longer periods than necessary can result 
in the blocking of other drivers and a 
reduction in system throughput. 



B.l CALLING $STMAP AND $MPUBM OR $STMPl AND $MPOBl 

To obtain UMRs through use of the $STMAP and $MPUBM or $STMPl and 
$MPUB1 routines, a driver must: 

1. If it uses $STMAP and $MPUBM or $STMPl and $MPUBl , allocate 6 
additional words for a mapping register assignment block at 
the end of the device's SCB (at S.MPR). If it uses $STMPl 
and $MPUB1, also provide a 10-word block. 

2. Call the routine $STMAP or $STMPl (Set Up UNIBUS Mapping 
Address) after getting the I/O packet. 

3. Call the routine $MPUBM or $MPUBl (Map UNIBUS to Memory) 
before initiating a transfer. 

These requirements are detailed in the following three subsections. 
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PDP-11/70 DRIVERS FOR NPR DEVICES 

Note that these routines are only required when the driver is 
performing a data transfer. 



B.1.1 Allocating a Mapping Register Assignment Block 

The status control block (SCB) of an NPR device requires an additional 
6 words. This 6-word mapping register assignment block is located at 
S.MPR, at the end of the SCB. It does not have to be initialized. 
Any initial contents are simply overwritten. 

The following example shows the allocation of a mapping register 
assignment block. The code is conditionalized on the AND of the two 
symbols M$$EXT and NI$$MGE (representing extended-memory support and 
memory-management unit support, respectively). 

.IF DF M$$EXT5:M$$MGE 

.BLKW 6 ;UMR WORK AREA 

.ENDC 

If the driver does not support parallel NPR operations reauiring UMR 
mapping, it calls $:STMAP and $MPUBM. If the driver supports parallel 
NPR operations requiring UMR mapping, it must call $STMP1 and $MPUBl. 
In the latter situation, the six additional words starting at S.MPE in 
the SCB are not used but must still be present. In addition, the 
driver must provide a 10-word mapping register assignment block for 
each data transfer to be mapped as specified in the description of 
$STMP1 in Chapter 5. 



B.1.2 Calling $STMAP or STMPl 

In the coding at the initiator entry point, after the call to $GTPKT, 
the NPR-device driver must call the routine $STMAP or $STMPl. These 
routines dynamically allocate required UMRs. If UMRs are not 
available immediately, the driver is blocked. Such blocking, if it 
occurs, is completely transparent to the driver. The driver resumes 
processing at fork level when the UMRs have been allocated. The 
register returns are absolutely identical whether or not blocking has 
occurred. 

$STMAP or $STMP1 stores into U.BUP and U.BUF+2 (in the UCB) a UNIBUS ^mtk, 

address that causes the appropriate UMR to be selected for mapping the ~^'^ 
transfer. The call to $STMAP or $STMP1 must be conditionalized on 
M$$EXTS.M$$MGE. 

Because $STMAP and $STMPl push the address of routine $D0UMR+2 on to 
the stack before returning to the caller, the driver should not use 
the stack for temporary data storage when it calls $STMAP or $STMP1. 



B.1.3 Calling $MPDBM or $MP0B1 

Before executing the transfer, the driver must call $MPUBM or $MPUB1. 
These routines get the buffer's 22-bit physical address, and load the 
UNIBUS mapping registers so that transfers are mapped directly to the 
task's space. The call to $MPUBM or $MPUB1 must be conditionalized on 
M$$EXT&M$$MGE. 



Jr^W ^Bfti 
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If the driver calls $STMAP and $MPUBM, the UMRs allocated to it are 
deallocated during the call to $IODON or $IOALT. If the driver calls 
$STMP1 and $MPUBl, it must call $DEUMR to deallocate any allocated 
UMRs before calling $IODON or $IOALT. 



B.2 CALLING $ASDHR and $DEOHR 

Some drivers may not require UMRs to be allocated all of the time, and 
yet require UMRs for periods of time longer than the normal time-frame 
between $GTPKT and $IODON (or $IOALT) . In such cases, there is a 
second procedure for allocating UMRs. 



Th 
dy 



rough use of the Executive routines $ASUMR and $DEUMR, a driver 
namically allocate, retain over a desired time-frame, and deall< 



can 
.locate 
UMRs. Refer to Section 5.3 for a description of the $ASUMR and $DEUMR 
routines. 



Similar to the $STMAP/$MPUBM procedure, the use of $ASUMR and $DEUMR 
also requires the allocation of a 6-word mapping register assignment 
block. In this instance, however, the block must not be located at 
offset S.MPR in the SCB. $IODON or $IOALT, when called, will attempt 
to deallocate the UMRs of a block found at location S.MPR. To avoid 
this, the mapping register assignment block could, for convenience, be 
located at S.MPR+2„ Alternatively, it could be dynamically allocated 
from the pool. Figure B-1 details the format of the 6-word block. 



M.LNK 


Link Word 


M.UMRA 


Address of first assigned UMR 


M.UMRN 


Number of assigned UMRs *4 


M.UMVl. 


Low 16 bits mapped by first assigned UiVIR 


M.UMVH 
M.BFVH 


High 6 bits of 
pliysical buffer address 


High 2 bits mapped by 
UMR (in bits 4 and 5) 


M.BFVL 


Low 16 bits of physical buffer address 



Figure B-1 Mapping Register Assignment Block 



B.3 STATICALLY ALLOCATING UMRs DURING SYSTEM GENERATION 

UMRs can be statically assigned during system generation. For systems 
with extended-memory support and memory-management unit support, the 
system generation procedure defines the symbol N$$UMR equal to a fixed 
number of UMRs, multiplied by 4, that are statically assigned to the 
system. Before assembling the Executive, the user can cause the 
static allocation of an additional number of UMRs by editing file 
RSXMC.MAC. The value of the symbol N$$UMR can then be increased to 
represent the additional number of desired UMRs multiplied by 4. 

RSXMC.MAC further defines the following three symbols, which describe 
the first UMR statically allocated during system generation: 

U$$MRN is the I/O page address of the first UMR register 
available for allocation to the user. 
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U$$MLO represents the low-order 16 bits of the 18-bit UNIBOS 
address mapped by this UMR. 

U$$MHI represents the high-order 2 bits of the 18-bit UNIBUS 
address. These 2 bits are in bit positions 4 and 5. 

These three symbols are not used by the system itself. They are 
available for the user's information. 



^^BH^fi 
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APPENDIX C 
SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.UK NDf SSSYDF 



.NLIST 



COPYRIGHT (C) 1974pl976,1977 

DIGITAL E.yUlPM£:NT CDHPOKATION , MAYNARD, MASS. 

THIS SOFTWARE IS HJRNISHLD UNDER A LICENSE FUR USE ONLY ON A 
SINGLE COMPUTER SYSTEM ANU MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OK OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NUT SUPPLIED BY DEC. 



.MACRO ABODFS,L,B 



TASK ABORT CODES 

NOTE: S.COAD-S.CFLT ARE ALSO SST VECTOR OFFSETS 



s 


COADs 


•B' 


0. 


s 


CSGF = 


'B' 


2. 


s 


,CBPT= 


'B 


4. 


s 


.CIOT= 


'B 


b. 


s 


.CILI= 


•B 


8. 


s 


.CEMT= 


•B 


10. 


s 


.CIRP= 


'B 


12. 


s 


.CFLT= 


•B 


14. 


s 


.CSST= 


'B 


16. 


s 


.CA5T= 


•B 


18. 


s 


.CABG= 


'B 


20. 


s 


.CLRF= 


•b 


22. 


s 


.CCRF= 


•B 


'24. 


s 


.IOMG= 


'B 


•26. 


s 


.PRTY= 


•B 


'28. 



(ODD ADDRESS AND TRAPS TO 4 

[SEGMENT FAULT 

rBREAK POINT OR TRACE TRAP 

!I0T INSTRUCTION 

r ILLEGAL OR RESERVED INSTRUCTION 

(WON RSX EMT INSTRUCTION 

rTRAP INSTRUCTION 

r 11/40 FLOATING PCfiNT EXCEPTION 

rSST ABORT-BAD STACK 

SAST ABORT-BAD STACK 

(ABORT VIA DIRECTIVE 

;TASK LOAD REQUEST FAILURE 

;TASK CHECKPOINT READ FAILURE 

;TASK EXIT WITH OUTSTANDING I/O 

;TASK MEMORY PARITY ERROR 



TASK TERMINATION NOTIFICATION MESSAGE CODES 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



T.NDhR='B'0 

T.NDSE='B'2 

T.NCVvf='B'4 

T.NCRE='B'6 

T.NDM0='B'8. 

T.NLDN='B'12. 

T.NLUP='B'14. 



•■DEVICfc NOT R&hOt 
;DEVICli SELECT ERROR 
••CHECKPUINT WRITE FAILURE 
.•CARD READER HARDWARE ERRUR 
••DISMUUNT COMPLETE 
;LIKK DOhN (NETWORKS) 
••LINK UP (NETWORKS) 



S^^l 



.MACRO 

.ENDM 

.ENDM 



ABULFS X,]i 



,iIF hUF SSSYDF , .LIST 



^^^^ 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



•iiK nor sssKUt 



•NLIST 



COPYKIGH'l' (C) 1974,1976,1977 

DIGITAL EtiUIiPHENT CORPUHATION, MAYNARD, MASS. 

IHIS SOFTWARE IS KUHMSHED UNDER A L,ICENS£ FUR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY bE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
AMY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE wHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNbHSHlP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC, 



.MACRO CLKDFS,L,B 



CLOCK QUEUE CONTROL BLOCK OFFSET DEFINITIONS 

CLOCK QUEUE CONTROL BLOCK 

THERE ARE FIVE TYPES OF CLOCK QUEUE CONTROL BLOCKS. EACH CONTROL BLOCK HAS 
THE SAME FORMAT IN THE FIRST FIVE WORDS AND DIFFERS IN THE REMAINING THREE. 

THE FOLLOWING CONTROL BLOCK TYPES ARE DEFINED: 



;- 

C.MRKT='B'0 

C.SCHD=*B'2 

C.SSHT='B'4 

C.SYST='B'6 

C.SYTK='B'8. 

C,CSTP='B'10. 



;MARK time REQUEST 

;TASK REQUEST WITH PERIODIC RESCHEDULING 

;SINGLE SHOT TASK REQUEST 

;SINGLE SHOT INTERNAL SYSTEM SUBROUTINE (IDENT) 

;SINGLE SHOT INTERNAL SYSTEM SUBROUTINE (TASK) 

;CLEAR STOP BIT (CONDITIONALIZED ON SHUFFLING) 



J CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET DEFINTIONS 



•ASECT 



C.LNK:'L' 
C.RQT:'L' 

c.efn: 'l* 

C.ICBr'L' 

C.tim:'l' 



.BLKW 1 



.BLKB 1 

.BLKB 1 

.BLKW 1 

.BLKW 2 



;CLOCK QUEUE THREAD WORD 

JREOUEST TYPE 

;EVENT FLAG NUMBER (MARK TIME ONLY) 

;TCB ADDRESS OR SYSTEM SUBROUTINE IDENTIFICATION 

;ABS0LUTE time when request COMES DUE 



; CLOCK QUEUE CONTROL BLOCK-HARK TIME DEPENDENT OFFSET DEFINITIONS 



.=C.TIM+4 
C.AST:'L' .BLKW 1 
C.SRC:'L' .BLKW 1 
C.DSTr'L' .BLKW 1 



.•START OF DEPENDENT AREA 

;AST ADDRESS 

;FLAG MASK WORD FOR 'BIS' SOURCE 

;ADDRESS OF 'BIS' DESTINATION 



'; CLOCK QUEUE CONTROL BLOCK-PERIODIC RESCHEDULING DEPENDENT OFFSET DEFINITIONS 



.=C.lIM+4 
C.RSI:'L' .BLKW 2 
C.U1C:'L' .BLKW 1 



,' START Ot DEPENDENT AREA 
;RESCHEDULE INTERVAL IN CLOCK .TICKS 
;SCHEDULING UlC 



I CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT DEPENDENT OFFSET DEFINITIONS 
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=C.TIM+4 

.BLKW 2 
.BLKW 1 



.•START OF DEPENDENT AREA 
;TWG UNUSED WORDS 
.•SCHEDULING UlC 



CLOCK OUEUE CONTROL BLOCK-SINGLE SHOT INTERNAL SUBROUTINE OFFSET DEFINITIONS 
THERE ARE TWO TVPE CODES FOR THIS TYPE OF REQUEST :'L' 

TYPE b=SlNGLE SHOT INTERNAL SUBROUTINE WITH A 16 BIT VALUE AS AN IDENTIFIER. 
TYPE e=SINGLE SHOT INTERNAL SUBROUTINE WITH A TCB ADDRESS AS AN IDENTIFIER. 



.=C.TIM+4 
C.SUB:'L' .BLKW 1 
C.AKS:'L' .BLKW 1 

.BLKW 1 
C.LGTHs'B'. 

.PSECT 



•MACRO CLKDFS X,Y 

.ENDh 

.ENDM 



.•START OF DEPENDENT AREA 

.-SUBROUTINE ADDRESS 

.•RELOCATION BASE (FOR LOADABLE DRIVERS) 

;ONE UNUSED MORD 

; LENGTH OF CLOCK UUEUE CONTROL BLOCK 



.IIF NDF SSSYDF 



.LIST 



-rf™^^^-! 
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.IIF 



NDF SSSyOF , .NLIST 



COPYRIGHT (C) 1974.1976,1977 

DIGITAL EOUIPMENT CClRPORATIUN , MAKNABD, MASS. 

THIS SOFTtoABh: IS FURNISHED UNDER A LICENSL FOR USE ONLY Oh A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EgUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO DCBDFS.L.B 



DEVICE CONTROL BLOCK 

THE DEVICE CONTROL BLOCK (DCB) DEFINES GENERIC INFORMATION ABOUT A DEVICE 
TYPE AND THE LOWEST AND HIGHEST UNIT NUMBERS. THERE IS AT LEAST ONE DCB 
FOR EACH DEVICE TYPE IN A SYSTEM. FOR EXAMPLE. IF THERE ARE TELETYPES IN A 
SYSTEM, THEN THERE IS AT LEAST ONE DCB WITH THE DEVICE NAME 'TT'. IK PART 
OF THE TELETYPES WERE IwTERFACED VIA DLll-A'S AND THE REST VIA A DHll, THEN 
THERE WOULD BE TWO DCB'S. ONE FOP ALL DLll-A INTERFACED TELETYPES, AND ONE 
FOR ALL DHll INTERFACED TELETYPES. 



.ASECT 



m • 


SO 






D. 


lnk: 


•L' .BLKW 




D 


ucb: 


•L' .BLKW 




D 


.nam: 


'L' .BLKW 




D 


.UNIT 


:'L' .BLKfc 


1 






.BLKB 




D 


.UCBL 


S'L' .BLKlF 


1 


D 


,dsp: 


•L' .BLKW 




D 


.msk: 


'L' .BLKW 








.BLKW 








.BLKW 








.BLKW 








.BLKW 








.BLKW 








.BLKW 








.BLKW 




D 


.PCB! 


•L* .BLKW 





;LINK to next DCB 

.•POINTER TO FIRST UNIT CONTROL BLOCK 

.•GENERIC DEVICE NAME 

fLOWEST UNIT NUMBER COVERED BY THIS DCB 

.'HIGHEST UNIT NUMBER COVERED BY THIS DCB 

.•LENGTH OF EACH UNIT CONTROL BLOCK IN BYTES 

.•POINTER TO DRIVER DISPATCH TABLE 

.•LEGAL FUNCTION MASK CODES 0-15. 

;CONTROL FUNCTION MASK CODES 0-15. 

JNOP'ED FUNCTION MASK CODES 0-15. 

;ACP FUNCTION MASK CODES 0-15. 

.•LEGAL FUNCTION MASK CODES 16.-31. 

.•CONTROL FUNCTION MASK CODES 16.-31. 

.•NOP'ED FUNCTION MASK CODES 16.-31. 

;ACP FUNCTION MASK CODES 16.-31. 

.•LOADABLE DRIVER PCB ADDRESS 



.PSECT 



DRIVER DISPATCH TABLE OFFSET DEFINITIONS 



D.VINI='B'0 
D.VCAN='B'2 
D.V0UT='B'4 
D.VPWF='B'6 



."DEVICE INITIATOR 

.•CANCEL CURRENT i/U FUNCTION 

.•DEVICE TIMEOUT 

;POWERFAIL RECOVERY 



.MACRO 

.ENDK 

.ENDM 

.IIF 



DCBDFS.X.Y 



NDF SSSYDF 



.LIST 
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.IIF NUF,SSSYDF,.«LIST 

.TITLE FllTBL FILES 11 TABLE DEFINITIONS 

.IDENT /0022/ 

COPYRIGHT (C) 1976, DIGITAL EQUIPMENT CORP.. MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDKR A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD HOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

ELLEN R SIMICH 16-JUN-76 3-MAR-77 IIM LOCK CHANGE 
ANDREW C. GOLDSTEIN 30 OCT 75 17:55 
PETER H. LIPMAN 12/27/73 

.MACRO FllDFS 

VOLUME CONTROL BLOCK 

.ASECT 






V.TRCT: 


.BLKW 


1 


V.IFWI; 


.BLKW 


1 




.IF 


DF,R$$11D 


V.STD: 


.BLKW 
.ENDC 


1 


V.FCB: 


.BLKW 


2 


V.IBLB: 


.BLKB 


1 


v.iBSZ: 


.BLKB 


1 




.BLKW 


1 


V.FMAX! 


.BLKW 


1 


v.wisz: 


.BLKb 


1 


V.SBCL: 


.BLKB 


1 


V.SBSZ: 


.BLKW 


1 


V.SBLBj 


.BLKB 


1 


V.FIEX: 


.BLKB 


1 




.BLKW 


1 




.IF 


DF.RSSllM 


v.vown: 


.BLKW 


1 


v.vPRO: 


.BLKW 


1 


V.VCHA: 


.BLKW 
.IFTF 


1 


V.FPRO: 


.BLKW 
.IFT 


1 


V.VFSQ: 


.BLKW 
.IFF 


1 




.BLKW 


1 




.ENDC 




V.FRBK: 


.BLKB 


1 


V.LRUC: 


.BLKB 


1 




.BLKW 


1 




.IF 


DF,RSS11D 


v.labl: 


.BLKB 
.ENDC 


12. 


V.STAT: 


.BLKB 


1 




VC.IFW: 


: 1 




VC.BMW: 


■■ 2 


v.ffnu: 


.BLKb 


1 


V.LGTH: 






; 

; FILE CONTROL 


BLOCK 


r 


•ASECT 




.=0 






F.LINK: 


.BLKM 


1 




.IF 


DK.PSSllD 


f.fext: 


.BLKW 


1 


F . STD : 


.BLKW 
.ENDC 


1 



/TRANSACTION COUNT 
.■INDEX FILE WINDOW 

;STD OF TASK CHARGED WITH NODE 

;FILE CONTROL BLOCK LIST HEAD 

; INDEX BIT MAP 1ST LBN HIGH BYTE 

; INDEX BIT MAP SIZE IN BLOCKS 

; INDEX BITMAP 1ST LBN LOW BITS 

;MAX no. of FILES ON VOLUME 

;DFLT SIZE OF WINDOW IN NO. OF RTRV PTRS 

;VALUE IS < 126. 

/STORAGE BIT MAP CLUSTER FACTOR 

.-STORAGE BIT MAP SIZE IN BLOCKS 

/STORAGE BIT MAP 1ST LBN HIGH BYTE 

.•DEFAULT FILE EXTEND SIZE 

/STORAGE BIT MAP 1ST LBN LOW BITS 

/VOLUME OWVER'S UIC 
/VOLUME PROTECTION 
/VOLUME CHARACTERISTICS 

/VOLUME DEFAULT FILE PROTECTION 

/VOLUME FILE SEQUENCE NUMBER 

/NOT USED 

/NUMBER OF FREE BLOCKS ON VOLUME HIGH BYTE 
/COUNT OF AVAILABLE LRU SLOTS IN FCB LIST 
/NUMBER OF FREE BLOCKS ON VOLUME LOW BITS 

/VOLUME LABKL (ASCII) 

/VOLUME STATUS BYTE, CONTAINING THE FOLLOWING 

/ INDEX FILE IS WRITE ACCESSED 

/ STORAGE BITMAP FILE IS WRITE ACCESSED 

/ FIRST FREE INDEX FILE BITMAP BLOCK 

/SIZE IN BYTES OF VCB 



/FCb CHAIN POINTER 

/POINTER TO EXTENSION FCB 
/STD OF TASK CHARGED WITH NODE 



^^^WS^ 
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k.knum: 


.BLKW 1 


f.fseq: 


.BLKW 1 




.BLKB 1 


f.fsqn: 


.BLKB I 


f.fown: 


.BLKW 1 


F.FPRO: 


.BLKW 1 


F.UCHA: 


•BLKB 1 


f.scha; 


.BLKB 1 



F.HDLB: .BLKW 



F.LBNi 



.BLKW 



F.SIZE! 


.BLKW 


2 


F.NACS: 


.BLKB 


1 


F.NLCK: 


.BLKB 


1 




S.STBK= 


.-F.Ltih 


F.STAT! 






F.NWAC: 


.BLKB 


1 




.BLKB 


1 




FC.WAC= 


100000 




FC.DIB= 


.40000 




FC.CEF= 


=20000 




FC.FCO=10000 


F.DREFI 


.BLKW 


1 


f.drnm: 


.BLKW 


1 




.IF 


DF,HSS11M 


F.FEXT: 


.BLKW 
.ENDC 


1 


f.fvbn: 


.BLKW 


2 


F.LKL: 


.BLKW 


1 


F.LGTH! 






• 

; WINDOW 




; 


.ASECT 




.=0 






W.CIL: 


.BLKW 


1 



WI.RDV=400 

WI.WRV=1000 

WI.EXT=2000 

WI.LCK=4000 

W1.DLK=10000 

WI.EXLS40000 

WI.BPSslOOOOO 



w.vbn: 

W.MISZ: 

w.fcb: 



W.FCB! 

w.std: 
w.vbn: 
w.wisz: 



m.lkl: 

W.RTRV: 



.IF 

.BLKB 

.BLKB 

.BLKW 

.BLKW 

.ENDC 

.IF 

.BLKW 

.BLKW 

.BLKB 

.BLKB 

.BLKW 

.ENDC 

.BLKW 



DF,R$$11M 

1 

1 

1 

1 

DF.RSSllD 

1 

1 

1 

1 

1 



;FILE NUMBER 

;FILE 5E0UENCE NUMBER 

;N0T USED 

;FILE SEGMENT NUMBER 

;F1LE OWNER'S UlC 

;FILE PROTECTION CODE 

;USER CONTROLLED CHARACTERISTICS 

.•SYSTEM CONTROLLED CHARACTERISTICS 

;FILE HEADER LOGICAL BLOCK NUMBER 

.'BEGINNING UK STATISTICS BLOCK 

;LBN of VIRTUAL BLOCK 1 IF CONTIGUOUS 

;0 IF NON CONTIGUOUS 

;SIZE OF FILE IN BLOCKS 

.•NO. OF ACCESSES 

;N0. OF LOCKS 

.-SIZE OF STATICS BLOCK 

.•FCB STATUS WORD 

.•NUMBER OF wRITE ACCESSORS 

; STATUS BITS FOR FCB CONSISTING OF 

;SET IF FILE ACCESSED FOR WRITE 

.•SET IF FCB IS IN DIRECTORY LRU 

.•SET IF DIRECTORY EOF NEEDS UPDATING 

;SET IF TRYING TO FORCE DIRECTORY CONTIG 

JDIRECTORY EOF BLOCK NUMBER 

;1S1 WORD OF DIRECTORY NAME 

.•POINTER TO EXTENSION FCB 

;STARTING VBN OF THIS FILE SEGMENT 
.•POINTER TO LOCKED BLOCK LIST FOR FILE 
;S1ZE IN BYTES OF FCB 



JLOW BYTE = # OF MAP ENTRIES ACTIVE 
fHIGH BYTE CONSISTS OF THE FOLLOWING BITS 
fREAD VIRTUAL BLOCK ALLOWED IF SET 
;wRITE VIRTUAL BLOCK ALLOWED IF SET 
.•EXTEND ALLOWED IF SET 
;SET IF LOCKED AGAINST SHARED ACCESS 
;SET IF DEACCESS LOCK ENABLED 
.•SET IF MANUAL UNLOCK DESIRED 
.•BYPASS ACCESS INTERLOCK IF SET 

;HIGH byte of 1ST VBN MAPPED BY WINDOW 
.•SIZE IN RTRV PTRS OF WINDOW (7 BITS3 
JLOW ORDER WORD OF 1ST VBN MAPPED 
.•FILE CONTROL BLOCK ADDRESS 



;FILE CONTROL BLOCK ADDRESS 
;STD OF TASK CHARGED WITH WIDOW NODE 
.•HIGH BYTE OF 1ST VBN MAPPED BY WINDOW 
;5IZE IN RTRV PTRS OF WINDOW (7 BITS) 
;LOW ORDER WORD OF 1ST VBN MAPPED 

JPOINTER TO LIST OF USERS LOCKED BLOCKS 
.•OFFSET TO 1ST RETRIEVAL POINTER IN WINDOW 



? LOCKED BLOCK LIST NODE 



.ASECT 



.=0 






L.LNK: 


.BLKW 


1 


L.wii: 


.BLKW 


1 




.IF 


DF.RSSllD 


L.STD! 


.BLKW 


1 


L.VBl: 


.BLKvt 


2 


L.VB2: 


.BLKW 


2 


L.CNT! 


.BLKB 


1 




.BLKB 


1 




.IFF 





;LINK TO NEXT NODE IN LIST 
{POINTER TO WINDOW FOR FIRST ENTRY 

.'POINTER TO STD OF TASK NODE CHARGED TO 
{STARTING VBN OF FIRST ENTRY 
.•STARTING VBN OF SECOND ENTRY 
.•COUNT FOR FIRST ENTRY 
.•COUNT FOR SECOND ENTRY 
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;hIGH ORDER VBN BYTE 
;COUNT FOR ENTRY 



li.VBl; 


.BLKB 


1 




L.CNT: 


.BLKB 


1 






.BLKM 


1 






.ENDC 






l.lgth: 


•PSECI 








.MACRO 


F11DF5 






• ENDM 


FllDFS 






.ENDM 


FllDFS 






.Ilf 


NDF.SSSYDK, 


.LIST 
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, IIF NDIF SSSYDF , .NLIST 



COPYRIGHT CO 1974,1976,1977 

DIGITAL EQUIPMENT CORPORATION. MAYNARD, MASS. 

THIS SOFTMARL IS FURNISHED UNDER A LICENSE FQK USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OK 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO AMY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO HDRDF6,L,B 



TASK HEADER OFFSET DEFINITIONS 



.SO 

H.CSP: 

H.HDLN 

H.EFLM 

H.CUIC 

H.DUIC 

H.IPS: 

H.IPC: 

h.isp: 

H.ODVA 
H.ODVL 
H.TKVA 
H.TKVL 
H.PFVA 
H.FPVA 
H.RCVA 
H.EFSV 
H.FPSA 

h.mnd: 

H.DSW: 
H.FCS: 
H.FORT 
H.OVLY 
H.VEXT 
H.SPRI 
H.NML: 
H.RRVA 

H.GARD 
H.NLUN 

h.lun: 



.ASECT 
'L'.BLKW 

:'l'.blkw 

: 'L'.BLKW 

; 'L'.BLKW 

: 'L'.BLKW 

•L'.BLKW 

'L'.BLKW 

'L'.BLKW 

: 'L'.BLKW 

:'L'.BLKW 

t'L'.BLKW 

I'L'.BLKW 

S 'L'.BLKW 

:'L'.BLKW 

:'L'.BLKW 

: 'L'.BLKW 

: 'L'.BLKW 

'L'.BLKW 

'L'.BLKW 

'L'.BLKW 

: 'L'.BLKW 

I'L'.BLKW 

: 'L'.BLKW 

:'L'.BLKB 

'L'.BLKB 

:'L'.BLKW 

.BLKW 
t'L'.BLKW 
: 'L'.BLKW 
'L'.BLKW 



.•CURRENT STACK POINTER 

.•HEADER LENGTH IN BYTES 

; EVENT FLAG MASK WORD AND ADDRESS 

;CURRENT TASK UIC 

;DEFAULT TASK UIC 

{INITIAL PROCESSOR STATUS WORD (PS) 

JINITIAL PROGRAM COUNTER (PC) 

; INITIAL STACK POINTER (SP) 

;ODT SST VECTOR ADDRESS 

;ODT SST VECTOR LENGTH 

;TASK SST VECTOR ADDRESS 

.•TASK SST VECTOR LENGTH 

JPOWER FAIL AST CONTROL BLOCK ADDRESS 

.•FLOATING POINT AST CONTROL BLOCK ADDRESS 

.•RECIEVE AST CONTROL BLOCK ADDRESS 

; EVENT FLAG ADDRESS SAVE ADDRESS 

.•POINTER TO FLOATING POINT/EAE SAVE AREA 

.•POINTER TQ NUMBER OF WINDOW BLOCKS 

;TASK DIRECTIVE STATUS WORD 

;FCS IMPURE POINTER 

.•FORTRAN IMPURE POINTER 

JOVERLAY IMPURE POINTER 

;WORK AREA EXTENSION VECTOR POINTER 

.•PRIORITY DIFFERENCE FOR SWAPPING 

{NETWORK MAILBOX LUN 

{RECEIVE BY REFERENCE AST CONTROL BLOCK ADDRESS 

{RESERVED WORDS 

{POINTER TO HEADER GUARD WORD 

{NUMBER OF LUN'S 

{START OF LOGICAL UNIT TABLE 



{ + 

{ WINDOW BLOCK OFFSETS 



W.BPCB: 'L'.BLKW 1 

w.blvr:'l'.blkw i 

W.BHVR: 'L'.BLKW 1 

W.BATT: 'L'.BLKW 1 

W.BSIZ:'L'.BLKW 1 

w.boff:'l'.blkw i 

W.BFPD: 'L'.BLKB 1 

w.bnpd:'l'.blkb i 



{PARTITION CONTROL BLOCK ADDRESS 
{LOW VIRTUAL ADDRESS LIMIT 
{HIGH VIRTUAL ADDRESS LIMIT 
{ADDRESS OF ATTACHMENT DESCRIPTOR 
{SIZE OF WINDOW IN 32W BLOCKS 
{PHYSICAL MEMORY OFFSET IN 32W BLOCKS 
{FIRST PDR ADDRESS 
{NUMBER OF PDR'S TO MAP 
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w.blpd:'l'.blkw i .-contents of last pdr 

W.BIiGH:'L' ;LENGTH OP MINDOW DESCRIPTOR 

•PSECT 

•MACRO HDRDfS X,K 

.ENOH 

.ENDM 

.Ilf NDF SSSKDF , .LIST 






i^^™^^ 
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.IIF NDF SSSYDF , .NLIST 



; COPYRIGHT (C) 1974,1976,1977 

; DIGITAL EQUIPMENT CORPORATIOh, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY MITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO HWDDF$,L,B 



HARDWARE REGISTER ADDRESSES AND STATUS CODES 



MPCSR='B'177746 

MPAR»'B'172100 

PIRQ='B'177772 

PROs'B'O 

PR1='B'40 

PR4s'B'200 

PR5a'B'240 

PR6='B'300 

PR7='B'340 

PS«'B'177776 

SWR='B'177570 

XPS='B'177564 



ADDRESS OF PDP-11/70 MEMORY PARITY REGISTER 
ADDRESS OF FIRST MEMORY PARITY REGISTER 
PROGRAMMED INTERRUPT REQUEST REGISTER 
PROCESSOR PRIORITY 

1 

4 

5 

6 

7 

PROCESSOR STATUS WORD 
CONSOLE SWITCH AND DISPLAY REGISTER 
CONSOLE TERMINAL PRINTER STATUS REGISTER 



PROCESSOR PRIORITY 
PROCESSOR PRIORITY 
PROCESSOR PRIORITY 
PROCESSOR PRIORITY 
PROCESSOR PRIORITY 



;t 



EXTENDED ARITHMETIC ELEMENT REGISTERS 



.IF DF ESSEAE 



AC='B'177302 
MQ='B'177304 
SC='B'177310 



.•ACCUMULATOR 
.•MULTIPLIER-QUOTIENT 
JSHIFT COUNT 



.ENDC 



MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES 



.IF DF MSSMGE 

KDSARO='fl'172360 
KDSUK0='B'172320 
KISAR0='B'172340 
KISAR5='B'172352 
KISAR6='B'172354 
KISAR7='B'172356 
KISDR0='B'172300 
KISDR6='B'172314 
KISDR7='B'172316 
SI5DR0a'B'172200 
UDSAR0='B'177660 
UDSDR0a'B'177620 
UISAR0='B'177640 
UISAR4=*B'177650 
UISAR5='B*177652 



.•KERNEL 


D PAR 





.•KERNEL 


D PDR 





.-KERNEL 


I PAR 





.•KERNEL 


1 PAR 


5 


;kernel 


I PAR 


fa 


; KERNEL 


I PAR 


7 


.•KERNEL 


I PDR 





;kernel 


I PDR 


6 


; KERNEL 


I PAR 


7 


; SUPERVISOR I 


PDR 


;USER D 


PAR 




;USER D 


PDR 




lUSER I 


PAR 




J USER I 


PAR 4 




;USER I 


PAR 5 
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UISAR6 
UISAR7 
UISORO 
UISDR4 
UISDRS 
UISDR6 
UISDR7 
UBMPRs 
CMODEs 
PMODEs 
SRO='B 
SR3x'B 



•B'177654 
•B'177656 
'B'177600 
='B'177610 
='B'177bl2 
'B'177614 
='B'177616 
•B'170200 
'B'140000 
•B'30000 
•177572 
•172516 

.ENDC 



USER 
USER 
USER 
USER 
USER 
USER 
USER 



PAR 
PAR 
PDR 
PDR 
PDR 
PDR 
PDR 



UNIBUS MAPPING REGISTER 
CURRENT MODE FIELD OF PS WORD 
PREVIOUS MODE FIELD OF PS WORD 
SEGMENT STATUS REGISTER 
SEGMENT STATUS REGISTER 3 



FEATURE SYMBOL DEFINITIONS 



FE.EXTa'B'l 

FE.MUP='B'2 

FE,EXV='B'4 

FE.DRVa'B'lO 

FE.PLA='B'20 

FE.CAL='B^40 

FE.PKT='B'100 

FE.EXP='B'2O0 

FE.LSI='B'400 

FE.CEX='B^20000 

FE.MXT='B^40000 

FE.NLGs'B'lOOOOO 



11/70 EXTENDED MEMORY SUPPORT 

MULTI-USER PROTECTION SUPPORT 

EXECUTIVE IS SUPPORTED TO 20K 

LOADABLE DRIVER SUPPORT 

PLAS SUPPORT 

DYNAMIC CHECKPOINT SPACE ALLOCATION 

PREALLOCATION OF I/O PACKETS 

EXTEND TASK DIRECTIVE SUPPORTED 

PROCESSOR IS AN LSI-11 

COM EXEC IS LOADED 

MCR EXIT AFTER EACH COMMAND MODE 

LOGINS DISABLED - MULTI-USER SUPPORT 



.MACHO 

.ENDM 

.ENDM 



HWDDFS X,Y 



.IIF NDF SSSYDF , .LIST 
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.IIF 



NDf s$$v;Dr 



.NLIST 



; COPYRIGHT (C) 1974,1976,1977 

DIGITAL. EQUIPMENT CORPOKATION. MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY MITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO LCBDFe,L,B 

^ 
LOGICAL ASSIGNMENT CONTROL BLOCK 

THE LOGICAL ASSIGNMENT CONTROL BLOCK (LCB) IS USED TO ASSOCIATE A 
LOGICAL NAME WITH A PHYSICAL DEVICE UNIT. LCB'S ARE LINKED TOGETHER 
TO FORM THE LOGICAL ASSIGNMENTS OF A SYSTEM. ASSIGNMENTS MAY BE ON 
A SYSTEM WIDE OR LOCAL (TERMINAL) BASIS. 







.ASECT 








. ■ 


:0 










L 


lnk: 


'L' .BLKW 


1 






L 


.NAM: 


'L' .BLKW 


1 






L 


.UNIT 


:'L' .LLKE 


1 






L 


.TYPE 


;'L' .BLKE 


1 






L 


.uct): 


•L* .BLKW 


1 






L 


.ASG: 


'L' .BLKW 


1 






L 


.LGTH 


s'B'.-L.LNK 










.PSECT 












.MACRO 


LCBDF$ 


X,Y 






.ENDM 












.ENDM 












.IIF 


NDF 


S8$YDF 



;LINK TO NEXT LCB 

.•LOGICAL NAME OF DEVICE 

.•LOGICAL UNIT NUMBER 

;TYPE OF ENTRY (OsSYSTEM WIDE) 

}TI UCB ADDRESS 

.•ASSIGNMENT UCB ADDRESS 

;LENGTH OF LCB 



.LIST 
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,I1F NDF SSSYDF , .NblST 



COPYRIGHT (C) 1974,1976,1977 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO PCBUF$ L,B,SYSDEF 



PARTITION CONTROL BLOCK OFFSET DEFINITIONS 



.ASECT 
.=0 

p.lnk:'l'.blkw i 

P.PRIr'L'.BLKB 1 

P.IQC:'L'.BLKb 1 

P.NAM: 'L'.BLKW 2 

P.SUB!'L*.BLKW 1 

p.main:'l'.blkw i 



;LINK TO NEXT PARTITION PCB 
;PRIORITY OF PARTITION 
;I/0 + 1/0 STATUS BLOCK COUNT 
{PARTITION MAME IN RAD50 
.•POINTER TO NEXT SUBPARTITION 
;POINTER TO MAIN PARTITION 



.IF NB SYSDEF 



.IF NDF M$$MGE 
P.HDRS'L' 

.ENDC 



; POINTER TO HEADER CONTROL BLOCK 



.IFTF 

P.BEL: 'L'.BLKW 1 
P.BLKS:'L' 

p.size:'l'.blkw i 

P.WAIT:'L'.BLKW 1 
P.SWSZ:'L'.BLKW 1 
P.BUSY:'L'.BLKB 2 
P.0WN:'L' 
P.TCB:'L'.BLKW 1 

p.stat:'l'.blkh i 



JprP'ffrJk 



{STARTING PHYSICAL ADDRESS OF PARTITION 

JSIZE OF PARTITION IN BYTES 
.'PARTITION WAIT QUEUE LISTHEAD (2 WORDS) 
.■PARTITION SWAP SIZE (SYSTEM ONLY} 
{PARTITION BUSY FLAGS 

.'TCB ADDRESS OF OWNER TASK 
{PARTITION STATUS FLAGS 



.IFT 



.IF DF MSSMGE 
P.HDR:'L' .BLKW 1 
.ENDC 



{POINTER TO HEADER CONTROL BLOCK 



P.PRO:*L' .BLKW 1 
P.ATT:*L' .BLKW 2 



{PROTECTION WORD (DEWR,DEWR,DEWR,DEWR] 
{ATTACHMENT DESCRIPTOR LISTHEAD 



.IF NDF PSSLAS 
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P.LGTHs'B'P.PRO 
.IFF 

P.LGTH='B'. 

.ENDC 



.■LENGTH OF PARTITION CONTROL BLOCK 



.•LENGTH OF PARTITION CONTROL BLOCK 



.IFF 
.PSECT 



PARTITION STATUS WORD BIT DEFINITIONS 



PS.OUTa'B 
PS.CKP='B 
PS.CKRs'B 
PS.CHKa'B 
PS.FXDs'B 
PS.PERs'B 
PS.LIOa'B 
PS,NSF='B 
PS.COMa'B 
PS.PICs'B 
PS.SYSs'B 
PS.DRVs'B 
PS.DELs'B 
PS.APRs'B 



•100000 

•40000 

•20000 

•10000 

•4000 

'2000 

•1000 

•400 

•200 

•100 

•40 

•20 

•10 

•7 



.'PARTITION IS OUT OF HEMORY( IbYES) 

/PARTITION CHECKPOINT IN PROGRESS ClaYES) 

.•PARTITION CHECKPOINT IS REQUESTED (1=YES) 

/PARTITION IS NOT CHECKPOINTABLE (IsyES) 

.•PARTITION IS FIXED (1=YES) 

••PARITY ERROR IN PARTITION (laYES) 

/MARKED BY SHUFFLER FOR LONG I/O (1=YES) 

/PARTITION IS NOT SHUFFLEABLE (IsYES) 

/LIBRARY OR COMMON BLOCK (IsYES) 

/POSITION INDEPENDENT LIBRARY OR COMMON (IsYES) 

/SYSTEM CONTROLLED PARTITION C1=YES) 

/DRIVER IS LOADED IN PARTITION (1=YES) 

/PARTITION SHOULD BE DELETED WHEN NOT ATTACHED (IsYES) 

/STARTING APR NUMBER MASK 



ATTACHMENT DESCRIPTOR OFFSETS 



.ASECT 
.=0 

A.PCBL/^L'.BLKW 1 

A.PRI/^L^.BLKB 1 

A.IOCt'L'.BLKB 1 

A.TCB:^L'.BLKW 1 

A.TCBL:'L'.BLKi(il 1 

A.STAT:'L'.BLKB 1 

A.MPCI:'L'.BLKB 1 

A.PCB/'L'.BLKW 1 
A.LGTHs^B'. 



/PCB ATTACJfIMENT QUEUE THREAD WORD 

/PRIORITY OF ATTACHED TASK 

/I/O COUNT THROUGH THIS DESCRIPTOR 

/TCB ADDRESS OF ATTACHED TASK 

/TCB ATTACHMENT QUEUE THREAD WORD 

/STATUS BYTE 

/MAPPING COUNT OF TASK THRU THIS DESCRIPTOR 

/PCB ADDRESS OF ATTACHED TASK 

/LENGTH OF ATTACHMENT DESCRIPTOR 



ATTACHMENT DESCRIPTOR STATUS BYTE BIT DEFINITIONS 



.PSECT 
AS.DEL='B'10 
AS.EXT=^B'4 
A5.WRT=^B'2 
AS.REDs'B'l 

.ENDC 



/TASK HAS DELETE ACCESS (1=YES) 

/TASK HAS EXTEND ACCESS (IsYES) 

/TASK HAS WRITE ACCESS (1=YES) 

/TASK HAS READ ACCESS (1=YES) 



.MACRO 

.ENUM 

.ENDM 



PCBDF5 X.Y.Z 



,IIF NDF 5SSYDF 



.LIST 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.UK NDf SSSXDF , .NLISX 



COPYRIGHT (C) 1974, 1977 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



j^WB^^ 



.MACRO PKTDF$,L,B,SYSDEF 



; + 



ASYNCHRONOUS SYSTEM TRAP CONTROL BLOCK OFFSET DEFINITIONS 



SOME POSITIONAL DEPENDENCIES BETWEEN THE OCB AND THE AST CONTROL BLOCK 
ARE RELIED UPON IN THE ROUTINE SFINXT IN THE MODULE SYSXT. 



.ASECT 
.=177774 

A.KSR5:'L' .BLKW 1 
A.DQSR:'L' .BLKW 1 

.BLKW 1 
A.CBLI'L' .BLKW 1 
A.BYTl'L' .BLKW 1 



A.AST:'L' 
A.NPRs'L' 



.BLKW 1 
.BLKW 1 



A.PRM;'L' .BLKW 1 



.•SUBROUTINE KISAR5 BIAS (A.CBLsO) 

;DE0UEU£ SUBROUTINE ADDRESS (A.CBLbO) 

>AST QUEUE THREAD WORD 

; LENGTH OF CONTROL BLOCK IN BYTES 

; NUMBER OF BYTES TO ALLOCATE ON TASK STACK 

;AST TRAP ADDRESS 

{NUMBER OF AST PARAMETERS 

; FIRST AST PARAMETER 



I/O PACKET OFFSET DEFINITIONS 



.=0 

I.LNK: 

I.PRI: 

I.EFN: 

i.tcb: 

I.LN2: 

i.ucb: 
I.FCN: 
I.IOSB 



last: 
i.prm: 



I.ATIL 



•L' 
•L' 



.ASECT 

'L' .BLKW 
'L' .BLKB 
'L' .BLKB 
.BLKW 
.BLKW 
'L' .BLKW 
'L* .BLKW 1 
:'L' .BLKW 

.3LKW 1 

.BLKW 
'L* .BLKW 
'L' .BLKW 

• BLKW 

.BLKW 
= 'B*. 



l.LGTHs'B*. 



I/O QUEUE THREAD WORD 

REQUEST PRIORITY 

EVENT FLAG NUMBER 

TCB ADDRESS OF REQUESTOR 

POINTER TO SECOND LUN WORD 

POINTER TO UNIT CONTROL BLOCK 

1/0 FUNCTION CODE 

.•VIRTUAL ADDRESS OF I/O STATUS BLOCK 
I/O STATUS BLOCK RELOCATON BIAS 
I/O STATUS BLOCK ADDRESS 
AST SERVICE ROUTINE ADDRESS 
RESERVED FOR MAPPING PARAMETER II 
PARAMETERS 1 TO 6 

USER MODE DIAGNOSTIC PARAMETER WORD 
MINIMUM LENGTH OF I/O PACKET (USED BY 
FILE SYSTEM TO CALCULATE MAXIMUM 
NUMBER OF ATTRIBUTES) 
LENGTH OF I/O REQUEST CONTROL BLOCK 



.PSECT 

.MACRO PKTDFS X,Y,Z 

.ENDM 

.ENDM 



.IIF NUF SSSYDF 



.LIST 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.Ilf 



NDf SSSiCF , .NLIST 



COPYRIGHT (CD 1974,1976,1977 

DIGITAL tOUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NUT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO SCBDF$,L,B,SYSDEF 



STATUS CONTROL BLOCK 

; THE STATUS CONTROL BLOCK (SCB) DEFINES THE STATUS OF A DEVICE CONTROLLER. 

; THERE IS ONE SCB FOR EACH CONTROLLER IN A SYSTEM. THE SCB IS POINTED TO 

; BY UNIT CONTROL BLOCKS. TO EXPAND ON THE TELETYPE EXAMPLE ABOVE, EACH TELE- 

; TYPE INTERFACED VIA A DLll-A WOULD HAVE A SCB SINCE EACH DLll-A IS AN IN- 

; DEPENDENT INTERFACE UNIT. THE TELETYPES INTERFACED VIA THE PHI J,, "0"!;^ *i;S° 

t EACH HAVE AN SCB SINCE THE DHll IS A SINGLE CONTROLLER BUT MULTIPLEXES MANY 

; UNITS IN PARALLEL. 







.ASECT 




.5 


177772 






s. 


RCNT 


•L 


.BLKB 




s. 


ROFF 


!'L 


.BLKB 




s. 


BMSV 


!'L 


' .BLKW 




s. 


BHSK 


:'L 


' .BLKW 




s. 


lhd: 


•L' 


.BLKw 


2 


s, 


PRI: 


•L' 


.BLKB 




s 


,vct: 


•L' 


.BLKB 




s 


.CTM: 


♦L' 


.BLKB 




s 


.ITM; 


'L' 


.BLKB 




s 


.CON: 


•L' 


.BLKB 




s 


.STS: 


•L' 


.BLKB 




s 


.CSR: 


'L' 


.BLKW 




s 


.PKT: 


•L' 


.BLKW 




s 


.FRK: 


•L' 


.BLKW 








• 


BLKW 








• 


BLKW 








• 


BLKW 





.•NUMBER OF REGISTERS TO COPY ON ERROR 

.•OFFSET TO FIRST DEVICE REGISTER 

;SAVED I/O ACTIVE BITMAP AND POINTER TO EMB 

JDEVICE I/O ACTIVE BIT MASK 

fCONTROLLER I/O QUEUE LISTHEAD 

.•DEVICE PRIORITY 

; INTERRUPT VECTOR ADDRESS /4 

.•CURRENT TIMEOUT COUNT 

; INITIAL TIMEOUT COUNT 

.•CONTROLLER INDEX 

.•CONTROLLER STATUS (OalDLE, 1=BUSY ) 

; ADDRESS OF CONTROL STATUS REGISTER 

;ADDRESS OF CURRENT I/O PACKET 

;FORK BLOCK LINK WORD 

;F0RK-PC 

;K0RK-R5 

;F0RK-R4 



.IF NB SYSDEF 

.IF DF LSSDRV & MSSMGE 

.BLKW 1 .'FORK-DRIVER RELOCATION BASE 

.ENDC 



S.CCB:'L' 
S.MPRI'L' .BLKW 6 

• IFF 

.PSECT 



;MIXED MASSBUS CHANNEL CONTROL BLOCK 

;ll/70 EXTENDED MEMORY UNIBUS DEVICE C-BLOCK 
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^STATUS CONTROL BLOCK PRIORITY BYTE CONDITION CODE STATUS BIT DEFINITIONS 



4^^, 



SP.EIPs'B'l 
SP.ENB='B'2 
SP.L0G='B'4 
SPARES 10 



.•ERROR IN PROGRESS (1=YES.) 
.•ERROR LOGGING ENABLED (0=YES) 
.•ERROR LOGGIhG AVAILABLE (laYES) 
.•SPARE BIT 



MAPPING ASSIGNMENT BLOCK (KOR UNIBUS MAPPING REGISTER ASSIGNMENT) 



M. 
M. 
M. 
H. 
M. 
M. 
M. 
M. 



.ASECT 


LNK:'L' 
UMRAr'L' 



bLKW 1 
BLKW 1 



UMRN:'L' .BLKW 1 

UMVL:'L' .BLKW 1 

UMVH:'L' .BLKB 1 

BFVH:'L' .BLKB 1 

BFVL:'L' .BLKW 1 
LGTH='B'. 



.•LINK WORD 

.•ADDRESS OF FIRST ASSIGNED UMR 

.•NUMBER OF UMR'S ASSIGNED * 4 

;LOw 16 BITS MAPPED BY 1ST ASSIGNED UMR 

.-HIGH 2 BITS MAPPED IN BITS 4 AND 5 

.•HIGH 6 BITS OF PHYSICAL BUFFER ADDRESS 

.•LOW 16 BITS OF PHYSICAL BUFFER ADDRESS 

.•LENGTH OF MAPPING ASSIGNMENT BLOCK 



.ENDC 

.PSECT 

.MACRO SCBDFS.X.J.Z 

.ENDM 

.ENDM 

.Ilf NDF SSSYDF . .LIST 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.IIK NDF SSSYDF , .NLIST 



COPYRIGHT (C) 1974.1976,1977 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION or THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE. OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

; THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
; NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
; EQUIPMENT CORPORATION. 

; DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
t ITS SOFTWARE ON EQUIPMENT kiIHICH IS NOT SUPPLIED BY DEC. 



.MACRO TCB»FS,L,B,SYSDEF 



; + 



; TASK CONTROL BLOCK OFFSET AND STATUS DEFINITIONS 

; 

; TASK CONTROL BLOCK 



.ASECT 



.=0 
T.LNK 
T.PRI 
T.IOC 



'L' .BLKW 1 

•L' .BLKB 1 

•L' .BLKB 1 
T.CPCB:'L' .BLKW 1 
T.NAM:'L' .BLKW 2 
T.RCVL:'L' .BLKW 2 
T.ASTL:'L' 
T.EFLG:'L' 
T.UCBI'L' 
T.TCBLI'L' 
T.STATS'L* 
T.STZI'L' 
T.ST3;'L' 
T.DPRI:'L' 
T.LBN:'L' .BLKB 3 
T.LDVI'L' .BLKW 1 
T.PCB:'L' .BLKW 1 
T.MXSZ:'L' .BLKW 1 
T.ACTL:'L' .BLKW 1 
T.ATTs'L* .BLKW 2 
T.0FF:'L' .BLKW 1 

.BLKB 1 
T.SRCT:'L' .BLKB 1 
T.RRFL:'L' .BLKW 2 

.IF NB SYSDEF 
.IF NDF PSSLAS 



.BLKW 2 
.BLKW 2 
.BLKW 1 
.BLKW 1 
.BLKW 1 
.BLKW 1 
.BLKW 1 
.BLKB 1 



UTILITY LINK WORD 

TASK PRIORITY 

I/O PENDING COUNT 

POINTER TO CHECKPOINT PCB 

TASK NAME IN RAD50 

RECEIVE QUEUE LISTHEAD 
lAST QUEUE LISTHEAD 
iTASK LOCAL EVENT FLAGS 1-32 
lUCB ADDRESS FOR PSEUDO DEVICE 'TI' 
I TASK LIST THREAD WORD 
(FIRST STATUS WORD (BLOCKING BITS) 
(SECOND STATUS WORD CSTATE BITS) 
(THIRD STATUS WORD (ATTRIBUTE BITS) 
(TASK'S DEFAULT PRIORITY 
rLBN OF TASK LOAD IMAGE 
rUCB ADDRESS OF LOAD DEVICE 
!PCB ADDRESS OF TASK PARTITION 
(MAXIMUM SIZE OF TASK IMAGE (MAPPED ONLY) 
(ADDRESS OF NEXT TASK IN ACTIVE LIST 
(ATTACHMENT DESCRIPTOR LISTHEAD 
(OFFSET TO TASK IMAGE IN PARTITION 
f RESERVED 

;SREF WITH EFN COUNT IN ALL RECEIVE QUEUES 
;RECE1VE BY REFERENCE LISTHEAD 



T.LGTHs'B'T.ATT 
.IFF 

T,.LGTH='B'. 

.ENDC 

T.EXT='B'0 

.IFF 



.•LENGTH OF TASK CONTROL BLOCK 



.'LENGTH OF TCB EXTENSION 
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TASK STATUS DfcFIMTIUNS 

FIRST STATUS WOKD (BLOCKING bITS) 






TS.EXEs'B'lOOOOO 

TS.RDN='B'40000 

TS.MSG='B'200C0 

TS.NRPs'B'lOOOO 

TS.RUN='B'4000 

TS.OUT='B'400 

TS.CKP='B'200 

TS.CKRs'B'lOO 



TASK BLOCKING STATUS MASK 



.•TASK NOT IN EXECUTION ClaYES) 

;I/0 RUN DOWN IN PROGRESS (IsYES) 

.•ABORT MESSAGE BEING OUTPUT (lalES) 

;TASK MAPPED TO NONRESIDENT PARTITION (IbYES) 

.•TASK IS RUNNING ON ANOTHER PROCESSOR (IxYES) 

.•TASK IS OUT OF MEMORY (1=YES) 

;TASK IS BEING CHECKPOINTED (IxYES) 

JTASK CHECKPOINT REQUESTED (IsYES) 



TS.BLK='B'TS.CKP!TS.CKR1TS.EXE!TS.MSG!TS.NRPSTS.0UT!TS.RDN f 

■f 



SECOND STATUS WORD (STATE BITS) 



T2.AST: 
T2.DSTi 
T2.CHK! 
T2.CKD! 
T2.BFX: 
T2.FXDS 
T2.TI0: 
T2.CAF= 
T2.HLTS 
T2.AB0S 
T2.STPS 
T2.STP= 
T2.SPN= 
T2.SPN: 
T2.WFR= 
T2.WFRS 

; + 

; THIRD STATUS WORD (ATTRIBUTE BITS) 



i'B'lOOOOO 
:'B'40000 
;'B'2O0O0 
•B'lOOOO 
'b'4O00 
•B'2O0O 
•B'lOOO 
•B'400 
•B'200 
•B'lOO 
•B'40 
•B'20 
•B'lO 
•B'4 
•B'2 
•B'l 



.•AST IN PROGRESS (1=YES) 

;AST RECOGNITION DISABLED (1*YES) 

.•TASK NOT CHECKPOINTABLE (l«YES) 

.•CHECKPOINTING DISABLED (IsYES) 

.•TASK BEING FIXED IN MEMORY (IsYES) 

••TASK FIXED IN MEMORY (IsYES) 

;TASK is ENGAGED IN TERMINAL I/O 

.•DYN CHECKPOINT SPACE ALLOCATION FAILURE 

.•TASK IS BEING HALTED (1=YES) 

.•TASK MARKED FOR ABORT (1»YES) 

.•TASK STOPPED (IsYES) 

(TASK STOPPED (IsYES) 

.•SAVED TS.SPN ON AST IN PROGRESS 

;TASK SUSPENDED (IsYES) 

;SAVED TS.WFR ON AST IN PROGRESS 

.•TASK IN WAITFOR STATE (IsYES) 



ji^^ix^ 



0llk 



T3.ACP: 
T3.PMD: 
T3.REM: 
T3.PRV! 
T3.MCR! 
T3.SLV: 
T3.CLI= 
T3.RSTS 
T3.NSDS 
T3.CAL: 
T3.R0V= 
T3.NETS 



•B'lOOOOO 

'B'40000 

•B'20000 

'B'lOOOO 

'B'4000 

•B'2000 

•B'lOOO 

•B'400 

•B'200 

•B'lOO 

'B'40 

'8'20 

.ENDC 



;ANCILLARY control processor (IsYES) 

.•DUMP TASK ON SYNCHRONOUS ABORT (QsYES) 

.•REMOVE TASK ON EXIT (IsYES) 

.•TASK IS PRIVILEGED (IsYES) 

.•TASK REQUESTED AS EXTERNAL MCR FUNCTION (IsYES) 

.•TASK IS A SLAVE TASK (IsYES) 

.•TASK IS A COMMAND LINE INTERPRETER (IsYGS) 

.•TASK IS RESTRICTED (IsYES) 

;TASK does NOT ALLOW SEND DATA 

fTASK HAS CHECKPOINT SPACE IN TASK IMAGE 

rTASK HAS RESIDENT OVERLAYS 

fNETWORK PROTOCOL LEVEL 



^^^VtuBi^ 



•PSECT 

•MACRO TCBDFS X.Y.Z 

.ENDM 

.ENDM 

.IIF NDF SS$YDF , .LIST 
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.IIF 



NDF S$$YOF , .hLXSI 



COPYRIGHT (C) 1974,1976,1977 

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 



.MACRO UCBDF$,L,B 

; + 

; UNIT CONTROL BLOCK 

I THE UNIT CONTROL BLOCK (UCB) DEFINES THE STATUS OF AN INDIVIDUAL DEVICE 

; UNIT AND IS THE CONTROL BLOCK THAT IS POINTED TO BY THE FIRST WORD OF 

s AN ASSIGNED LUN. THERE IS ONE UCB FOR EACH DEVICE UNIT OF EACH DCB. THE 

; UCB'S ASSOCIATED WITH A PARTICULAR DCB ARE CONTIGUOUS IN MEMORY AND ARE 

t POINTED TO BY THE DCB. UCB'S ARE VARIABLE LENGTH BETWEEN DCB'S BUT ARE 

; OF THE SAME LENGTH FOR A SPECIFIC DCB. TO FINISH THE TELETYPE EXAMPLE ABOVE, 

; EACH UNIT ON BOTH INTERFACES WOULD HAVE A UCB. 



.ASECT 


.=177774 




U.LU1C:'L' 


.BLKW 1 


U.OWNI'L' 


.BLKW 1 


U.DCBI'L' 


.BLKW 1 


U.REDI'L* 


.BLKW 1 


U.CTL:'L' 


.BLKB 1 


U.STSr'L* 


.BLKB 1 


U.UNIT:'L 


' .BLKB 1 


U.ST2:'L' 


.BLKB 1 


U.CWH'L* 


.BLKW 1 


U.CW2:'L' 


.BLKW 1 



U.CW3:'L' .BLKW 1 
U.CW4:'L' .BLKW 1 
U.SCB:'L' .BLKW 1 
U.ATT:'L' .BLKW 1 
U.BUF:'L' .BLKW 1 
.BLKW 1 
U.CNT;'L' .BLKW 1 
U.ACP='B'U.CNT+2 
U.VCB='B'U.CNT+4 
U.CBF='B'U.CNT+2 
U.UIC = 'B'U.CINT+<9.*2> 



;L0GIN UIC - MULTI USER SYSTEMS ONLY 

.•OWNING TERMINAL - MULTI USER SYSTEMS ONLY 

;BACK POINTER TO DCB 

.•POINTER TO REDIRECT UNIT UCB 

;CONTROL PROCESSING FLAGS 

;UNIT STATUS 

.•PHYSICAL UNIT NUMBER 

;UNIT STATUS EXTENSION 

;FIRST DEVICE CHARACTERISTICS WORD 

;SECOND DEVICE CHARACTERISTICS WORD 

fTHIRD DEVICE CHARACTERISTICS WORD 

;F0URTH DEVICE CHARACTERISTICS WORD 

; POINTER TO SCB 

;TCB ADDRESS OF ATTACHED TASK 

.•RELOCATION BIAS OF CURRENT I/O REQUEST 

>BUFFER ADDRESS OF CURRENT I/O REQUEST 

;BYTE COUNT OF CURRENT I/O REQUEST 

; ADDRESS OF TCB OF MOUNTED ACP 

JADDRESS OF VOLUME CONTROL BLOCK 

;CONTROL BUFFER RELOCATION AND ADDRESS 

JTERMINAL UIC (TERMINALS ONLY) 



.PSECT 



DEVICE TABLE STATUS DEFINITIONS 

DEVICE CHARACTERISTICS WORD I (U.CWl) DEVICE TYPE DEFINITION BITS. 



DV.RECs'B'l 

DV.CCLa'B'2 

DV.TTY=*B'4 

DV.DIRs'B'lO 

DV.SDIa'B'20 

DV.SQD='B'40 

DV.MXDs'B'lOO 



;RECORD ORIENTED DEVICE C1=YES) 
;CARRIAGE CONTROL DEVICE (1=YES) 
.•TERMINAL DEVICE (IsYES) 
;FILE STRUCTURED DEVICE (1=YES) 
.•SINGLE DIRECTORY DEVICE (1=YES) 
{SEQUENTIAL DEVICE C1=YES) 
;MAS5 bus DEVICE C1=YES) 
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DV.UMD='B'200 

DV.SWL='B'100O 

DV.ISP='B'2000 

IJV.05P=:'B'4000 

DV.PSE='B'10000 

UV.COM='B'20O0O 

DV.K11='B'40000 

DV.MNT='B'10OO0O 

; + 

; lEHMINAL UEPENDEM' CHARACTERISTICS WORD 2 CU.CW2) BIT DEFINITIONS 



;USER MODE DIAGNOSTICS SUPPORTED (1: 
;UNIT SOFTWARE WRITE LOCKED (laYES) 
.•INPUT SPOOLED DEVICE (1=YES) 
.•OUTPUT SPOOLED DEVICE (1=YES) 
.-PSEUDO DEVICE (1=YES) 

.•DEVICE IS MOUNTABLE AS COM CHANNEL 

.•DEVICE IS MOUNTABLE AS Fll DEVICE (tsYES) 
;DEVICE is MOUNTABLE (IsYES) 



sYES) 



ClsYES) 



U2.DH1: 
U2.DJ1: 
U2.RMT: 
U2.L8S: 
U2.NEC! 
U2.CRT= 
U2.ESC= 
U2.L0G: 
U2.SLV: 
U2.DZ1: 
U2.HLDS 
U2.AT.= 
U2.PRV= 
U2.L3SS 
U2.VT5S 
U2.LWC: 

; + 

; RH11-RS03/RS04 CHARACTERISTICS WORD 2 {U.CW2) BIT DEFINITIONS 



•B'lOOOOO 

'B'40000 

•B'20000 

'B'lOOOO 

•B'4000 

•B'2000 

•B'lOOO 

•B'400 

•B'200 

•B'lOO 

•B'40 

•B'20 

'B'lO 

•B'4 

•B'2 

•B'l 



.•UNIT IS A MULTIPLEXER C1=YES) 

;UNIT IS A DJll (IsYESJ 

;UNIT IS REMOTE CI=YES) 

;UNIT IS LA180S (IsYES) 

;D0«'T ECHO SOLICITED INPUT (1«YES) 

;UNIT IS A CRT (1=YES) 

;UNIT GENERATES ESCAPE SEQUENCES (1=YES) 

JUSER LOGGED ON TERMINAL (0=YES) 

.•UNIT IS A SLAVE TERMINAL (1=YES) 

••UNIT IS A DZll (1=YES) 

.TERMINAL IS IN HOLD SCREEN MODE (1=YES) 

.•MCR COMMAND AT. BEING PROCESSED (IsYES) 

.•UNIT IS A PRIVILEGED TERMINAL (IsYES) 

.'UNIT IS A LA30S TERMINAL (laYES) 

.•UNIT IS A VI05B TERMINAL (laYES) 

/LOWER CASE TO UPPER CASE CONVERSION (1=YES) 



"^nll 



U2.RO4='B'10000O ;UNIT IS A RS04 (1=YES) 

; + 

; RHll-TUlb CHARACTERISTICS WORD 2 (U.CW2) BIT DEFINITIONS 

;UNIT IS A 7 CHANNEL DRIVE (1=YES) 
UNIT CONTROL PROCESSING FLAG DEFINITIONS 



mk 



U2.7CH='B'10000 

+ 



UC.ALG='B'200 

UC.NPRs'B'lOO 

UC.QUE='B'40 

UC.PWF=*B'20 

UC.ATTs'B'lO 

UC.KILsi'B'4 

UC.LGH='B'3 



UNIT STATUS BIT DEFINTIONS 



.•BYTE ALIGNMENT ALLOWED (IsNO) 
.-DEVICE IS AN NPR DEVICE (IsYES) 
;CALL DRIVER BEFORE QUEUING (IsYES) 
;CALL DRIVER AT POWERFAIL ALWAYS (1=YES) 
;CALL DRIVER ON ATTACH/DETACH (1=YES) 
;CALL DRIVER AT I/O KILL ALWAYS (IsYES) 
.•TRANSFER LENGTH MASK BITS 



i''^?^ 



US.BSY='B'200 
OS.MNTs'B'lOO 
US.FOR='B'40 
US.MDM='B'20 



;UNIT IS BUSY (IsyeS) 

.•UNIT IS MOUNTED (OsYES) 

.-UNIT IS MOUNTED AS FOREIGN VOLUME (1=YES) 

;UNIT IS MARKED FOR DISMOUNT (IsYES) 



CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS 



US.ABO='B'l 
US.MDEs'B'2 



;UNIT IS MARKED FOR ABORT IF NOT READY (1=YES) 
.•UNIT IS IN 029 TRANSLATION NODE (IsYES) 



FILES-11 DEPENDENT UNIT STATUS BITS 



US.WCK='B'10 
US.SPU='B'2 



; WRITE CHECK ENABLED (IsYES) 
;UNIT IS SPINNING UP (IsYES) 
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; TERMINAL DEPENDENT UNIT STATUS BIT DEFINITIONS 

;- 



US.DSBs'B'lO 
US.CRWs'B'4 
US.ECHs'B'2 
US.OUTs'B'l 



;UNIT IS DISABLED (1=YES) 

;UNIT IS WAITING FOR CARRIER (1=YES) 

JUNIT HAS ECHO IN PROGRESS (1=YES) 

.•UNIT IS EXPECTING OUTPUT INTERRUPT ClaYES) 



LPSll DEPENDENT UNIT STATUS BIT DEFINITIONS 



US.FRK! 
US.SHR: 



■■'b'2 

!'B'l 



;FORK IN PROGRESS (IsYES) 

.•SHAREABLE FUNCTION IN PROGRESS (Os'B'YES) 



; + 

; ANSI MAGTAPE DEPENDANT UNIT STATUS BITS 

US.LAB='B'4 t UNIT HAS LABELED TAPE ON IT C1=YES) 



; + 

; UNIT 

;- 

US.OFL! 
US. RED: 
US.PUBi 
US.UMD: 



STATUS EXTENSION (U.ST2) BIT DEFINITIONS 



s'B'l 
i'B'2 
i'B'4 
:'B'10 



•MACRO UCBDF$,X,Y 
.ENDM 

.ENDM 



;UNIT OFFLINE C1=YES) 

;UNIT REDIRECTABLE (0=YES) 

JUNIT IS PUBLIC DEVICE (1=YES) 

;UNIT ATTACHED FOR DIAGNOSTICS (1=YES) 



.IIF 



NDF SS$YDF , .NLIST 
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Accessing shared data bases, 2-9 

$ACHCK, 5-2 

$ACHKB, 5-2 

ACP function, 2-16 

ACP function mask, 4-12 

Address check, 

($ACHKB/$ACHCK) , 5-2 
Address-checking and relocation, 

6-9 
Address doubleword, A-1 
Addressing, 22-bit, B-1 
Allocate Core Buffer ($ALOCB) , 

5-3 
$ALOCB, 5-3 

APR 5, 3-11, 3-15, 4-29 
APR 6, 3-15, 4-5 
Assign UNIBUS Mapping Registers, 

($ASUMR) , 5-4, B-3 
$ASUMR, 5-4, B-3 



Bootstrapping, 2-4, 3-26 



Cancel I/O entry point, 2-4, 

3-2, 4-10 
CDA, 3-17 
Characteristics, device, 4-23, 

4-24 
CINT$ directive, 3-1 
$CLINS, 5-5 
Clock Queue Insertion ($CLINS) , 

5-5 
Conditional routines, 5-1 
Connect to interrupt vector 

directive, 3-1 
Control function, 2-16 
Control function mask, 4-12 
Control status register (CSR) , 

4-18 
Controller number, 2-13, 4-18, 

4-27 
Conventions, programming, 2-13 
Crash dump analysis support 

routine (CDA) , 3-17 
$CRAVL, 3-24 
CSR, 4-18 



Data bases, accessing shared, 

2-9 
Data structures, 2-5 to 2-9 

interrelation of, 2-17 

summary, 2-20 

system, C-1 
DCb", 2-5, 2-17, 2-19, 3-3, 4-7 



DCB fields, 

D.DSP, 3-4, 4-9 
D.LNK, 3-4, 3-8, 4-8 
D.MSK, 3-4, 4-5, 4-11 
D.NAM, 3-4, 4-9 
D.PCB, 3-4, 4-7, 4-13 
D.UCB, 3-4, 3-8, 4-8 
D.UCBL, 3-4, 4-9 
D.UNIT, 3-4, 4-9 
DCB fields, required, 3-4 
DDT, 2-17, 2-19, 3-2, 4-9, 4-10 
$DEACB, 3-25, 5-6 
Deallocate Core Buffer ($DEACB) , 

3-25, 5-6 
Deassign UNIBUS Mapping Registers, 

($DEUMR) , 5-7, B-3 
Debugging, driver, 3-12 to 3-25, 
aids, 3-13 to 3-18 
fault isolation, 3-18 to 3-20 
fault tracing, 

after unintended loop, 3-24 
critical pointers, 3-20 
using stack and register 
dump, 3-22 

without display, 3-23 
Debugging aids, 3-13 to 3-18 
Definitions, symbolic, C-1 
$DEUMR, 5-7, B-3 
$DEVHD word, 2-17, 2-18, 2-19 
Device characteristics, 4-23, 

4-24 
Device Control Block (DCB) , 

2-5, 2-17, 2-19, 3-3, 4-7 
Device interrupt entry point, 

2-3, 3-2 
Device interrupt vector, 2-9, 

2-13, 3-3, 3-6, 4-17, 4-26 
Device Message Output ($DVMSG) , 

5-8 
Device timeout, 4-17 
Device timeout entry point, 2-4, 

3-2, 4-10 
Directive Parameter Block (DPB) , 

2-5, 2-8, 2-16, 4-5 
DPB, 2-5, 2-8, 2-16, 4-5 
$DRDSP, 3-23 
Driver, 

coding example, 6-1 
debugging, 3-12 to 3-25 
entry points, 2-3, 2-4, 3-2 
function, 1-1 

loadable, see loadable drivers 
multicontroller, 2-13, 4-27 
Non-MASSBUS NPR, B-1 
resident, see resident drivers 
role in RSX-llM, 2-3, 2-4 
Driver code, 

loadable, 3-2, 3-3 
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Driver code (Cont.)» 

overview, 3-2 

resident, 3-2, 3-3 
Driver dispatch table (DDT), 2-17, 

2-19, 3-2, 4-9, 4-10 
DRQIO, 2-10 
$DVMSG, 5-8 



Error logging, 3-3 

Executive debugging tool (XDT) , 

3-14, 3-15, 3-18 
Executive services, 2-lQ to 2-12 
Executive stack and register 

dump routine, 3-13, 3-14, 

3-19 



Fault isolation, 3-18 to 3-20 

Fault tracing, 3-20 

FCB, 2-17, 2-19 

FCP, 2-3 

PCS, 2-1, 2-2 

File control block (FCB), 2-17, 

2-19 
File control primitives (FCB) , 

2-3 
File control services (FCS) , 2-1, 

2-2 
Flow of an I/O request, 2-15 
$FORK, 2-9, 2-12, 2-15, 4-17, 

4-19, 5-9 
Fork block, 4-19 

Fork level processing, 2-9, 2-15 
Fork list, 2-9 
$F0RK1, 5-10 
Function mask values, I/O, 4-14 



Get Byte ($GTBYT) , 5-11 
Get Packet, 

($GTPKT) , 2-11, 2-17, 4-18, 

4-25, 4-27, 5-12 
Get Word ($GTWRD) , 5-13 
GLUN$ directive, 4-23 
$GTBYT, 5-11 
$GTPKT, 2-11, 2-17, 4-18, 4-25, 

4-27, 5-12 
$GTWRD, 5-13 



$HEADR pointer, 3-20, 3-23 
HWDDF$ macro, 4-17 



I/O Done and I/O Done Alternate 
Entry, 
($IODON/$IOALT) , 2-12, 5-16 



I/O Finish, 

($IOFIN), 2-11, 5-17 
I/O function mask values, 4-14 
I/O hierarchy, 2-1 
I/O initiator entry point, 2-4, 

2-11, 3-2, 4-10 
I/O Packet, 2-8, 2-16, 4-2, 4-18 
I/O Packet fields, 

LAST, 4-5 

I.EFN, 4-3 

I.FCN, 3-24, 4-4 

I.IOSB, 4-4 

I.LNK, 4-2 

I.LN2, 4-4 

I.PRI, 4-3 

I.PRM, 4-5 

I.TCB, 4-4 

I.UCB, 4-4 
I/O Queue, 2-8, 4-16 
I/O request, 

flow of, 2-15 
I/O Status Block (lOSB), 2-10, 

2-16, 2-17, 4-4, 4-7 
ICB, 4-28, 4-29 
Initiator entry point, I/O, 2-4, 

2-11, 3-2, 4-10 
INITL module, 3-19 
Interrupt control block (ICB) , 

4-28, 4-29 
Interrupt entry point, device, 

2-3, 3-2 
Interrupt Exit, 

($INTXT) , 2-13, 5-15 
Interrupt Save, 

($INTSV), 2-11, 2-12, 2-13 to 
2-15, 4-28, 5-14 
Interrupt vector, device, 2-9, 
2-13, 3-3, 3-6, 4-17, 4-26 
$INTSV, 2-11, 2-12, 2-13 to 2-15, 

4-28, 5-14 
INTSV$ macro, 2-12 to 2-15, 

4-27 to 4-29 
$INTXT, 2-13, 5-15 
$IOALT, 2-12, 5-16 
$IODON, 2-12, 2-17, 4-18, 5-16 
!?IOFIN, 2-11, 5-17 
lOSB, 2-10, 2-16, 2-17, 4-4, 4-7 



Legal function mask, 4-11 
LOAD command, 2-4, 3-8, 3-10, 
3-12, 3-27, 4-17, 4-18, 
4-26, 4-28 
Loadable drivers, 

adding to system library, 3-10 
assembling, 3-10 
creating the data base for, 
3-9 
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Loadable drivers (Cont.)/ 
dynamic initialization of 

interrupt vector, 4-26 
LD$xx symbol for, 3-3 
loading, 3-12 

nature of data base for, 3-8 
rebuilding and reincorporating, 

3-27 
source code, 3-2, 3-3 
specifying support for, 3-2 
task building, 3-10 to 3-12 
Logical unit table (LUT) , 2-18, 

4-4 
LUT, 2-18, 4-4 



Map UN I BUS to memory, 

($MPUBM, $MPUB1) , 5-18, 

B-2 
Mapping register assignment 

block, B~2, B-3 
Masks, I/O function, 4-11 

establishing, 4-14 
$MPUBM, 5-18, B-2 
$MPUB1, 5-18.1, B-2 
Multicontroller drivers, 2-13, 

4-27 



Non-MASSBUS NPR device drivers, 

B-1 
No-op function, 2-16 
No-op function mask, 4-12 
NPR device drivers, 4-25, B-1 



Panic dump, 3-16, 3-17, 3-19 

Paper tape punch driver, 6-3 

Partition control block (PCB) , 
4-13, 4-14 

PCB, 4-13, 4-14 

$PKiWL, 3-24 

Power failure entry point, 2-4, 
3-2, 4-10 

Process, 

characteristics, 2-13 
states, 2-10 

Processing, 

at fork level, 2-9, 2-15 
at priority 7, 2-9, 2-11, 2-14 
at priority of interrupting 
source, 2-9, 2-14, 4-17 

Programming conventions, 2-13 

Programming protocol, 2-13 

Protocol, programming, 2-13 

$PTBYT, 5-19 

$PTWRD, 5-20 



Put Byte ($PTByT) , 5-19 
Put Word ($PTWRD) , 5-20 



$QINSP, 5-21 

QIO directive, 2-2, 2-16 
Queue Insertion by Priority 
($QINSP) , 5-21 



Record management services 

(RMS), 2-1, 2-2 
REDIRECT command, 4-21 
Register conventions, system- 
state, 5-1 
$RELOC, 5-22 
Relocate ($RELOC) , 5-22 
Relocating and address-checking, 

6-9 
Resident drivers, 

creating the data base for, 3-6 
incorporating, 3-6 
initializing the device 

interrupt vector, 3-6, 4-26 
padding space in, 3-3 
rebuilding and reincorporating, 

3-25 
source code, 3-2, 3-3 
RMS, 2-1, 2-2 



SCB, 2-6, 2-18, 2-19, 3-3, 4-16, 

B-2 
SCB fields, 

S.CON, 3-5, 4-18, 4-27 

S.CSR, 3-5, 4-18 

S.CTM, 3-5, 4-17 

S.FRK, 3-5, 4-19 



ITM, 
LHD, 
MPR, 
PKT, 



3-5, 4-17 
3-5, 3-8, 



4-2, 4-16 
4-19, B-2, B-3 
4-18 



3-5, 

3-5, 3-24, 
.PRI, 3-5, 4-17 
,STS, 3-5, 4-18 
S.VCT, 3-5, 4-17 
SCB fields, required, 3-5 
Set Up UNIBUS Mapping Address, 

($STMAP, $STMP1) , 5-23, B-2 
Shared data bases, accessing, 

2-9 
Special user buffers, 6-9 
SST fault, 3-22, 3-23 
Stack and register dump routine, 

3-13, 3-14, 3-19 
Stack structure, 3-22, 3-23 
Status Control Block (SCB), 2-6, 
2-18, 2-19, 3-3, 4-16, B-2 
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Status information, device- 
independent, 4-22, 4-23 
$STKDP pointer, 3-20, 3-23 
$STiyiAP, 5-23, B-2 
$STMP1, 5-24, B-2 
Symbolic definitions, C-1 
Symbolic UMR addresses, B-3 
Symbols, 

LD$xx, 3-3, 4-29 

M$$EXT, B-2 

M$$MGE, B-2 

N$$UMR, B-2 

U$$MHI, B-3 

U$$MLO, B-3 

U$$MRN, B-3 

$USRTB, 3-6 

$xxINP, 3-2, 4-7 

$xxINT, 3-2, 4-7 

$xxOUT, 3-2, 4-7 

$xxTBL, 3-2 
SYSCM pointers, 

$CRAVL, 3-24 

$HEADR, 3-20, 3-2 3 

$STKDP, 3-20, 3-23 

$TKTCB, 3-20, 3-23 
SYSTB, 3-19 

System data structures, C-1 
System-state register conventions, 
5-1 



UCB fields (Cont.) , 

U.CNT, 3-5, 4-26 

U.CTL, 2-8, 3-5, 4-21 

U.CWl, 3-5, 4-23 

U.CW2, 3-5, 4-24 

U.CW3, 3-5, 4-24 

U.CW4, 3-5, 4-24 

U.DCB, 3-4, 3-8, 4-9, 4-21 

U.LUIC, 3-4, 4-9, 4-19 

U.OWN, 3-4, 4-9, 4-20 

U.RED, 3-4, 3-8, 4-21 

U.SCB, 3-5, 3-8, 4-24 

U.STS, 3-5, 4-22 

U.ST2, 3-5, 4-23 

U.UNIT, 3-5, 4-23 
UCB fields, required, 3-4, 3-5 
UMR addresses, symbolic, B-3 
UMRs, B-1 
UMRs, allocating during system 

generation, B-2 
UNIBUS Mapping Registers (UMRs) , 

B-1 
Unit control block (UCB), 2-6, 

2-18, 2-19, 3-3, 4-19 
UNLOAD command, 3-8, 3-27, 4-26 
User buffers, special, 6-9 
$USRTB, 3-6 
USRTB, 3-6 
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Task header, 2-17, 2-18, 3-20, 

3-21 
Timeout entry point, device, 

2-4, 3-2, 4-10 
$TKTCB pointer, 3-20, 3-2 3 
Transfer function, 2-16 



UCB, 2-6, 2-18, 2-19, 3-3, 4-19 
UCB fields, 

U.ATT, 3-5, 4-25 

U.BUF, 3-5, 4-25, B-2 



VCB, 2-18, 2-19 
Virtual MCR (VMR) , 3-26 
Volume control block (VCB), 2-18, 
2-19 



Window block (WB) , 2-17, 2-18, 
2-19, 4-4 



XDT, 3-14, 3-15, 3-18 
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B-l/B-2 

B-3/B-4 

Index-l/Index-2 

Index-3/Index-4 

Reader's Comments 



New Page 

Title Page/Copyright Page 

iii/iv through vii/viii 

2-13/2-14 

3-3/3-4 

3-9/3-10 

4-9/4-10 

4-11/4-12 

4-12.1/blank 

4-13/4-14 

4-15/4-16 

4-19/4-20 through 4-23/4-24 

5-15/5-16 

5-18.1/blank 

5-23/5-24 

6-3/6-4 

B-l/B-2 

B-3/B-4 

Index- 1/ Index- 2 

Index-3/Index-4 

Reader's Comments 



Additional copies of this update to the RSX-llM Guide to Writing 
an I/O Driver may be ordered from the Software Distribution 
Center, Digital Equipment Corporation, Maynard, Massachusetts 
01754. Order Code: AD-2 600D-T1. The order code of the base 
manual is AA-2600D-TC. 
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